Debian Codegraph @

sdk/metric/example_test.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package metric_test
5
6 import (
7 "context"
8 "fmt"
9 "log"
10 "regexp"
11
12 "go.opentelemetry.io/otel"
13 "go.opentelemetry.io/otel/attribute"
14 "go.opentelemetry.io/otel/sdk/instrumentation"
15 "go.opentelemetry.io/otel/sdk/metric"
16 "go.opentelemetry.io/otel/sdk/metric/exemplar"
17 "go.opentelemetry.io/otel/sdk/resource"
18 semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
19 )
20
21 // To enable metrics in your application using the SDK,
22 // you'll need to have an initialized [MeterProvider]
23 // that will let you create a [go.opentelemetry.io/otel/metric.Meter].
24 //
25 // Here's how you might initialize a metrics provider.
26 func Example() {
27 // Create resource.
28 res, err := resource.Merge(resource.Default(),
29 resource.NewWithAttributes(semconv.SchemaURL,
30 semconv.ServiceName("my-service"),
31 semconv.ServiceVersion("0.1.0"),
32 ))
33 if err != nil {
34 log.Fatalln(err)
35 }
36
37 // This reader is used as a stand-in for a reader that will actually export
38 // data. See https://pkg.go.dev/go.opentelemetry.io/otel/exporters for
39 // exporters that can be used as or with readers.
40 reader := metric.NewManualReader()
41
42 // Create a meter provider.
43 // You can pass this instance directly to your instrumented code if it
44 // accepts a MeterProvider instance.
45 meterProvider := metric.NewMeterProvider(
46 metric.WithResource(res),
47 metric.WithReader(reader),
48 metric.WithCardinalityLimit(2000),
49 )
50
51 // Handle shutdown properly so that nothing leaks.
52 defer func() {
53 err := meterProvider.Shutdown(context.Background())
54 if err != nil {
55 log.Fatalln(err)
56 }
57 }()
58
59 // Register as global meter provider so that it can be used via otel.Meter
60 // and accessed using otel.GetMeterProvider.
61 // Most instrumentation libraries use the global meter provider as default.
62 // If the global meter provider is not set then a no-op implementation
63 // is used, which fails to generate data.
64 otel.SetMeterProvider(meterProvider)
65 }
66
67 func ExampleView() {
68 // The NewView function provides convenient creation of common Views
69 // construction. However, it is limited in what it can create.
70 //
71 // When NewView is not able to provide the functionally needed, a custom
72 // View can be constructed directly. Here a custom View is constructed that
73 // uses Go's regular expression matching to ensure all data stream names
74 // have a suffix of the units it uses.
75
76 re := regexp.MustCompile(`[._](ms|byte)$`)
77 var view metric.View = func(i metric.Instrument) (metric.Stream, bool) {
78 // In a custom View function, you need to explicitly copy
79 // the name, description, and unit.
80 s := metric.Stream{Name: i.Name, Description: i.Description, Unit: i.Unit}
81 // Any instrument that does not have a unit suffix defined, but has a
82 // dimensional unit defined, update the name with a unit suffix.
83 if re.MatchString(i.Name) {
84 return s, false
85 }
86 switch i.Unit {
87 case "ms":
88 s.Name += ".ms"
89 case "By":
90 s.Name += ".byte"
91 default:
92 return s, false
93 }
94 return s, true
95 }
96
97 // The created view can then be registered with the OpenTelemetry metric
98 // SDK using the WithView option.
99 _ = metric.NewMeterProvider(
100 metric.WithView(view),
101 )
102
103 // Below is an example of how the view will
104 // function in the SDK for certain instruments.
105 stream, _ := view(metric.Instrument{
106 Name: "computation.time.ms",
107 Unit: "ms",
108 })
109 fmt.Println("name:", stream.Name)
110
111 stream, _ = view(metric.Instrument{
112 Name: "heap.size",
113 Unit: "By",
114 })
115 fmt.Println("name:", stream.Name)
116 // Output:
117 // name: computation.time.ms
118 // name: heap.size.byte
119 }
120
121 func ExampleNewView() {
122 // Create a view that renames the "latency" instrument from the v0.34.0
123 // version of the "http" instrumentation library as "request.latency".
124 view := metric.NewView(metric.Instrument{
125 Name: "latency",
126 Scope: instrumentation.Scope{
127 Name: "http",
128 Version: "0.34.0",
129 },
130 }, metric.Stream{Name: "request.latency"})
131
132 // The created view can then be registered with the OpenTelemetry metric
133 // SDK using the WithView option.
134 _ = metric.NewMeterProvider(
135 metric.WithView(view),
136 )
137
138 // Below is an example of how the view will
139 // function in the SDK for certain instruments.
140 stream, _ := view(metric.Instrument{
141 Name: "latency",
142 Description: "request latency",
143 Unit: "ms",
144 Kind: metric.InstrumentKindCounter,
145 Scope: instrumentation.Scope{
146 Name: "http",
147 Version: "0.34.0",
148 SchemaURL: "https://opentelemetry.io/schemas/1.37.0",
149 },
150 })
151 fmt.Println("name:", stream.Name)
152 fmt.Println("description:", stream.Description)
153 fmt.Println("unit:", stream.Unit)
154 // Output:
155 // name: request.latency
156 // description: request latency
157 // unit: ms
158 }
159
160 func ExampleNewView_wildcard() {
161 // Create a view that sets unit to milliseconds for any instrument with a
162 // name suffix of ".ms".
163 view := metric.NewView(
164 metric.Instrument{Name: "*.ms"},
165 metric.Stream{Unit: "ms"},
166 )
167
168 // The created view can then be registered with the OpenTelemetry metric
169 // SDK using the WithView option.
170 _ = metric.NewMeterProvider(
171 metric.WithView(view),
172 )
173
174 // Below is an example of how the view will
175 // function in the SDK for certain instruments.
176 stream, _ := view(metric.Instrument{
177 Name: "computation.time.ms",
178 Unit: "1",
179 })
180 fmt.Println("name:", stream.Name)
181 fmt.Println("unit:", stream.Unit)
182 // Output:
183 // name: computation.time.ms
184 // unit: ms
185 }
186
187 func ExampleNewView_drop() {
188 // Create a view that drops the "latency" instrument from the "http"
189 // instrumentation library.
190 view := metric.NewView(
191 metric.Instrument{
192 Name: "latency",
193 Scope: instrumentation.Scope{Name: "http"},
194 },
195 metric.Stream{Aggregation: metric.AggregationDrop{}},
196 )
197
198 // The created view can then be registered with the OpenTelemetry metric
199 // SDK using the WithView option.
200 _ = metric.NewMeterProvider(
201 metric.WithView(view),
202 )
203 }
204
205 func ExampleNewView_attributeFilter() {
206 // Create a view that removes the "http.request.method" attribute recorded
207 // by the "latency" instrument from the "http" instrumentation library.
208 view := metric.NewView(
209 metric.Instrument{
210 Name: "latency",
211 Scope: instrumentation.Scope{Name: "http"},
212 },
213 metric.Stream{AttributeFilter: attribute.NewDenyKeysFilter("http.request.method")},
214 )
215
216 // The created view can then be registered with the OpenTelemetry metric
217 // SDK using the WithView option.
218 _ = metric.NewMeterProvider(
219 metric.WithView(view),
220 )
221 }
222
223 func ExampleNewView_exponentialHistogram() {
224 // Create a view that makes the "latency" instrument from the "http"
225 // instrumentation library to be reported as an exponential histogram.
226 view := metric.NewView(
227 metric.Instrument{
228 Name: "latency",
229 Scope: instrumentation.Scope{Name: "http"},
230 },
231 metric.Stream{
232 Aggregation: metric.AggregationBase2ExponentialHistogram{
233 MaxSize: 160,
234 MaxScale: 20,
235 },
236 },
237 )
238
239 // The created view can then be registered with the OpenTelemetry metric
240 // SDK using the WithView option.
241 _ = metric.NewMeterProvider(
242 metric.WithView(view),
243 )
244 }
245
246 func ExampleNewView_exemplarreservoirproviderselector() {
247 // Create a view that makes all metrics use a different exemplar reservoir.
248 view := metric.NewView(
249 metric.Instrument{Name: "*"},
250 metric.Stream{
251 ExemplarReservoirProviderSelector: func(agg metric.Aggregation) exemplar.ReservoirProvider {
252 // This example uses a fixed-size reservoir with a size of 10
253 // for explicit bucket histograms instead of the default
254 // bucket-aligned reservoir.
255 if _, ok := agg.(metric.AggregationExplicitBucketHistogram); ok {
256 return exemplar.FixedSizeReservoirProvider(10)
257 }
258 // Fall back to the default reservoir otherwise.
259 return metric.DefaultExemplarReservoirProviderSelector(agg)
260 },
261 },
262 )
263
264 // The created view can then be registered with the OpenTelemetry metric
265 // SDK using the WithView option.
266 _ = metric.NewMeterProvider(
267 metric.WithView(view),
268 )
269 }
270
271 func ExampleWithExemplarFilter_disabled() {
272 // Use exemplar.AlwaysOffFilter to disable exemplar collection.
273 _ = metric.NewMeterProvider(
274 metric.WithExemplarFilter(exemplar.AlwaysOffFilter),
275 )
276 }
277
278 func ExampleWithExemplarFilter_custom() {
279 // Create a custom filter function that only offers measurements if the
280 // context has an error.
281 customFilter := func(ctx context.Context) bool {
282 return ctx.Err() != nil
283 }
284 _ = metric.NewMeterProvider(
285 metric.WithExemplarFilter(customFilter),
286 )
287 }