github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/util/metric/doc.go (about)

     1  // Copyright 2016 The Cockroach Authors.
     2  //
     3  // Use of this software is governed by the Business Source License
     4  // included in the file licenses/BSL.txt.
     5  //
     6  // As of the Change Date specified in that file, in accordance with
     7  // the Business Source License, use of this software will be governed
     8  // by the Apache License, Version 2.0, included in the file
     9  // licenses/APL.txt.
    10  
    11  /*
    12  Package metric provides server metrics (a.k.a. transient stats) for a
    13  CockroachDB server. These metrics are persisted to the time-series database and
    14  are viewable through the web interface and the /_status/metrics/<NODEID> HTTP
    15  endpoint.
    16  
    17  Adding a new metric
    18  
    19  First, add the metric to a Registry.
    20  
    21  Next, call methods such as Counter() and Rate() on the Registry to register the
    22  metric. For example:
    23  
    24  	exec := &Executor{
    25  		...
    26  		selectCount: sqlRegistry.Counter("sql.select.count"),
    27  		...
    28  	}
    29  
    30  This code block registers the metric "sql.select.count" in sql.Registry. The
    31  metric can then be accessed through the "selectCount" variable, which can be
    32  updated as follows:
    33  
    34  	func (e *Executor) doSelect() {
    35  		// do the SELECT
    36  		e.selectCount.Inc(1)
    37  	}
    38  
    39  To add the metric to the web UI, modify the appropriate file in
    40  "ui/ts/pages/*.ts". Someone more qualified than me can elaborate, like @maxlang.
    41  
    42  Sub-registries
    43  
    44  It's common for a Registry to become part of another Registry through the "Add"
    45  and "MustAdd" methods.
    46  
    47  	func NewNodeStatusMonitor(serverRegistry *registry) {
    48  		nodeRegistry := metric.NewRegistry()
    49  
    50  		// Add the registry for this node to the root-level server Registry. When
    51  		// accessed from through the serverRegistry, all metrics from the
    52  		// nodeRegistry will have the prefix "cr.node.".
    53  		serverRegistry.MustAdd("cr.node.%s", nodeRegistry)
    54  	}
    55  
    56  Node-level sub-registries are added by calling:
    57  
    58  	(*metric.MetricRecorder).AddNodeRegistry(YOUR_NODE_SUBREGISTRY)
    59  
    60  Testing
    61  
    62  After your test does something to trigger your new metric update, you'll
    63  probably want to call methods in TestServer such as MustGetSQLCounter() to
    64  verify that the metric was updated correctly. See "sql/metric_test.go" for an
    65  example.
    66  
    67  Additionally, you can manually verify that your metric is updating by using the
    68  metrics endpoint.  For example, if you're running the Cockroach DB server with
    69  the "--insecure" flag, you can use access the endpoint as follows:
    70  
    71  	$ curl http://localhost:8080/_status/nodes/1
    72  
    73  	(some other output)
    74  	"cr.node.sql.select.count.1": 5,
    75  	(some other output)
    76  
    77  Note that a prefix and suffix have been added. The prefix "cr.node." denotes that this metric
    78  is node-level. The suffix ".1" specifies that this metric is for node 1.
    79  */
    80  package metric