diff --git a/content/en/docs/concepts/signals/metrics.md b/content/en/docs/concepts/signals/metrics.md index bea47a52849e..b56b0378d906 100644 --- a/content/en/docs/concepts/signals/metrics.md +++ b/content/en/docs/concepts/signals/metrics.md @@ -98,10 +98,10 @@ Some examples of use cases for metrics include: ## Views -A View provides SDK users with the flexibility to customize the metrics that are -output by the SDK. They can customize which metric instruments are to be -processed or ignored. They can customize aggregation and what attributes are to -be reported on metrics. +A view provides SDK users with the flexibility to customize the metrics output +by the SDK. You can customize which metric instruments are to be processed or +ignored. You can also customize aggregation and what attributes you want to +report on metrics. ## Language Support diff --git a/content/en/docs/instrumentation/go/manual.md b/content/en/docs/instrumentation/go/manual.md index e71e5602a554..c09f8f8df8fc 100644 --- a/content/en/docs/instrumentation/go/manual.md +++ b/content/en/docs/instrumentation/go/manual.md @@ -465,8 +465,7 @@ example). Counters can be used to measure a non-negative, increasing value. -For example, here's how you might report the number of calls for an HTTP -handler: +For example, here's how you report the number of calls for an HTTP handler: ```go import ( @@ -497,7 +496,7 @@ func init() { UpDown counters can increment and decrement, allowing you to observe a cumulative value that goes up or down. -For example, here's how you might report the number of items of some collection: +For example, here's how you report the number of items of some collection: ```go import ( @@ -537,8 +536,8 @@ func removeItem() { Histograms are used to measure a distribution of values over time. -For example, here's how you might report a distribution of response times for an -HTTP handler: +For example, here's how you report a distribution of response times for an HTTP +handler: ```go import ( @@ -573,7 +572,7 @@ func init() { Observable counters can be used to measure an additive, non-negative, monotonically increasing value. -For example, here's how you might report time since the application started: +For example, here's how you report time since the application started: ```go import ( @@ -604,7 +603,7 @@ func init() { Observable UpDown counters can increment and decrement, allowing you to measure an additive, non-negative, non-monotonically increasing cumulative value. -For example, here's how you might report some database metrics: +For example, here's how you report some database metrics: ```go import ( @@ -656,8 +655,8 @@ func registerDBMetrics(db *sql.DB, meter metric.Meter, poolName string) (metric. Observable Gauges should be used to measure non-additive values. -For example, here's how you might report memory usage of the heap objects used -in application: +For example, here's how you report memory usage of the heap objects used in +application: ```go import ( @@ -720,6 +719,101 @@ func init() { } ``` +### Registering Views + +A view provides SDK users with the flexibility to customize the metrics output +by the SDK. You can customize which metric instruments are to be processed or +ignored. You can also customize aggregation and what attributes you want to +report on metrics. + +Every instrument has a default view, which retains the original name, +description, and attributes, and has a default aggregation that is based on the +type of instrument. When a registered view matches an instrument, the default +view is replaced by the registered view. Additional registered views that match +the instrument are additive, and result in multiple exported metrics for the +instrument. + +You can use the +[`NewView`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#NewView) +function to create a view and register it using the +[`WithView`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#WithView) +option. + +For example, here's how you create a view that renames the `latency` instrument +from the `v0.34.0` version of the `http` instrumentation library to +`request.latency`: + +```go +view := metric.NewView(metric.Instrument{ + Name: "latency", + Scope: instrumentation.Scope{ + Name: "http", + Version: "0.34.0", + }, +}, metric.Stream{Name: "request.latency"}) + +meterProvider := metric.NewMeterProvider( + metric.WithView(view), +) +``` + +For example, here's how you create a view that makes the `latency` instrument +from the `http` instrumentation library to be reported as an exponential +histogram: + +```go +view := metric.NewView( + metric.Instrument{ + Name: "latency", + Scope: instrumentation.Scope{Name: "http"}, + }, + metric.Stream{ + Aggregation: metric.AggregationBase2ExponentialHistogram{ + MaxSize: 160, + MaxScale: 20, + }, + }, +) + +meterProvider := metric.NewMeterProvider( + metric.WithView(view), +) +``` + +The `NewView` function provides a convenient way of creating views. If `NewView` +can't provide the functionalities you need, you can create a custom +[`View`](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#View) directly. + +For example, here's how you create a view that uses regular expression matching +to ensure all data stream names have a suffix of the units it uses: + +```go +re := regexp.MustCompile(`[._](ms|byte)$`) +var view metric.View = func(i metric.Instrument) (metric.Stream, bool) { + // In a custom View function, you need to explicitly copy + // the name, description, and unit. + s := metric.Stream{Name: i.Name, Description: i.Description, Unit: i.Unit} + // Any instrument that does not have a unit suffix defined, but has a + // dimensional unit defined, update the name with a unit suffix. + if re.MatchString(i.Name) { + return s, false + } + switch i.Unit { + case "ms": + s.Name += ".ms" + case "By": + s.Name += ".byte" + default: + return s, false + } + return s, true +} + +meterProvider := metric.NewMeterProvider( + metric.WithView(view), +) +``` + ## Logs The logs API is currently unstable, documentation TBA. diff --git a/content/en/docs/instrumentation/js/manual.md b/content/en/docs/instrumentation/js/manual.md index 6d6b61b6256b..4cb2347547bb 100644 --- a/content/en/docs/instrumentation/js/manual.md +++ b/content/en/docs/instrumentation/js/manual.md @@ -1452,8 +1452,8 @@ counter.add(-1); Histograms are used to measure a distribution of values over time. -For example, here's how you might report a distribution of response times for an -API route with Express: +For example, here's how you report a distribution of response times for an API +route with Express: {{< tabpane text=true langEqualsHeader=true >}} {{% tab TypeScript %}} diff --git a/static/refcache.json b/static/refcache.json index 1e17f62df126..8202be72a42c 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -4391,6 +4391,22 @@ "StatusCode": 200, "LastSeen": "2023-09-11T14:33:25.420952095Z" }, + "https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#NewView": { + "StatusCode": 200, + "LastSeen": "2023-09-15T09:41:38.164411819Z" + }, + "https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#View": { + "StatusCode": 200, + "LastSeen": "2023-09-15T09:41:38.432556144Z" + }, + "https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#With": { + "StatusCode": 200, + "LastSeen": "2023-09-15T09:41:38.295762202Z" + }, + "https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric#WithView": { + "StatusCode": 200, + "LastSeen": "2023-09-15T16:34:14.034832295Z" + }, "https://pkg.go.dev/go.opentelemetry.io/otel/sdk/resource": { "StatusCode": 200, "LastSeen": "2023-09-11T14:33:25.721659015Z"