example_test.go

Documentation: go.opentelemetry.io/otel/metric

     1  // Copyright The OpenTelemetry Authors
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package metric_test
    16  
    17  import (
    18  	"context"
    19  	"database/sql"
    20  	"fmt"
    21  	"net/http"
    22  	"runtime"
    23  	"time"
    24  
    25  	"go.opentelemetry.io/otel"
    26  	"go.opentelemetry.io/otel/attribute"
    27  	"go.opentelemetry.io/otel/metric"
    28  	semconv "go.opentelemetry.io/otel/semconv/v1.21.0"
    29  )
    30  
    31  var meter = otel.Meter("my-service-meter")
    32  
    33  func ExampleMeter_synchronous() {
    34  	// Create a histogram using the global MeterProvider.
    35  	workDuration, err := meter.Int64Histogram(
    36  		"workDuration",
    37  		metric.WithUnit("ms"))
    38  	if err != nil {
    39  		fmt.Println("Failed to register instrument")
    40  		panic(err)
    41  	}
    42  
    43  	startTime := time.Now()
    44  	ctx := context.Background()
    45  	// Do work
    46  	// ...
    47  	workDuration.Record(ctx, time.Since(startTime).Milliseconds())
    48  }
    49  
    50  func ExampleMeter_asynchronous_single() {
    51  	_, err := meter.Int64ObservableGauge(
    52  		"DiskUsage",
    53  		metric.WithUnit("By"),
    54  		metric.WithInt64Callback(func(_ context.Context, obsrv metric.Int64Observer) error {
    55  			// Do the real work here to get the real disk usage. For example,
    56  			//
    57  			//   usage, err := GetDiskUsage(diskID)
    58  			//   if err != nil {
    59  			//   	if retryable(err) {
    60  			//   		// Retry the usage measurement.
    61  			//   	} else {
    62  			//   		return err
    63  			//   	}
    64  			//   }
    65  			//
    66  			// For demonstration purpose, a static value is used here.
    67  			usage := 75000
    68  			obsrv.Observe(int64(usage), metric.WithAttributes(attribute.Int("disk.id", 3)))
    69  			return nil
    70  		}),
    71  	)
    72  	if err != nil {
    73  		fmt.Println("failed to register instrument")
    74  		panic(err)
    75  	}
    76  }
    77  
    78  func ExampleMeter_asynchronous_multiple() {
    79  	// This is just a sample of memory stats to record from the Memstats
    80  	heapAlloc, err := meter.Int64ObservableUpDownCounter("heapAllocs")
    81  	if err != nil {
    82  		fmt.Println("failed to register updown counter for heapAllocs")
    83  		panic(err)
    84  	}
    85  	gcCount, err := meter.Int64ObservableCounter("gcCount")
    86  	if err != nil {
    87  		fmt.Println("failed to register counter for gcCount")
    88  		panic(err)
    89  	}
    90  
    91  	_, err = meter.RegisterCallback(
    92  		func(_ context.Context, o metric.Observer) error {
    93  			memStats := &runtime.MemStats{}
    94  			// This call does work
    95  			runtime.ReadMemStats(memStats)
    96  
    97  			o.ObserveInt64(heapAlloc, int64(memStats.HeapAlloc))
    98  			o.ObserveInt64(gcCount, int64(memStats.NumGC))
    99  
   100  			return nil
   101  		},
   102  		heapAlloc,
   103  		gcCount,
   104  	)
   105  	if err != nil {
   106  		fmt.Println("Failed to register callback")
   107  		panic(err)
   108  	}
   109  }
   110  
   111  // Counters can be used to measure a non-negative, increasing value.
   112  //
   113  // Here's how you might report the number of calls for an HTTP handler.
   114  func ExampleMeter_counter() {
   115  	apiCounter, err := meter.Int64Counter(
   116  		"api.counter",
   117  		metric.WithDescription("Number of API calls."),
   118  		metric.WithUnit("{call}"),
   119  	)
   120  	if err != nil {
   121  		panic(err)
   122  	}
   123  	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
   124  		apiCounter.Add(r.Context(), 1)
   125  
   126  		// do some work in an API call
   127  	})
   128  }
   129  
   130  // UpDown counters can increment and decrement, allowing you to observe
   131  // a cumulative value that goes up or down.
   132  //
   133  // Here's how you might report the number of items of some collection.
   134  func ExampleMeter_upDownCounter() {
   135  	var err error
   136  	itemsCounter, err := meter.Int64UpDownCounter(
   137  		"items.counter",
   138  		metric.WithDescription("Number of items."),
   139  		metric.WithUnit("{item}"),
   140  	)
   141  	if err != nil {
   142  		panic(err)
   143  	}
   144  
   145  	_ = func() {
   146  		// code that adds an item to the collection
   147  		itemsCounter.Add(context.Background(), 1)
   148  	}
   149  
   150  	_ = func() {
   151  		// code that removes an item from the collection
   152  		itemsCounter.Add(context.Background(), -1)
   153  	}
   154  }
   155  
   156  // Histograms are used to measure a distribution of values over time.
   157  //
   158  // Here's how you might report a distribution of response times for an HTTP handler.
   159  func ExampleMeter_histogram() {
   160  	histogram, err := meter.Float64Histogram(
   161  		"task.duration",
   162  		metric.WithDescription("The duration of task execution."),
   163  		metric.WithUnit("s"),
   164  		metric.WithExplicitBucketBoundaries(.005, .01, .025, .05, .075, .1, .25, .5, .75, 1, 2.5, 5, 7.5, 10),
   165  	)
   166  	if err != nil {
   167  		panic(err)
   168  	}
   169  	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
   170  		start := time.Now()
   171  
   172  		// do some work in an API call
   173  
   174  		duration := time.Since(start)
   175  		histogram.Record(r.Context(), duration.Seconds())
   176  	})
   177  }
   178  
   179  // Observable counters can be used to measure an additive, non-negative,
   180  // monotonically increasing value.
   181  //
   182  // Here's how you might report time since the application started.
   183  func ExampleMeter_observableCounter() {
   184  	start := time.Now()
   185  	if _, err := meter.Float64ObservableCounter(
   186  		"uptime",
   187  		metric.WithDescription("The duration since the application started."),
   188  		metric.WithUnit("s"),
   189  		metric.WithFloat64Callback(func(_ context.Context, o metric.Float64Observer) error {
   190  			o.Observe(float64(time.Since(start).Seconds()))
   191  			return nil
   192  		}),
   193  	); err != nil {
   194  		panic(err)
   195  	}
   196  }
   197  
   198  // Observable UpDown counters can increment and decrement, allowing you to measure
   199  // an additive, non-negative, non-monotonically increasing cumulative value.
   200  //
   201  // Here's how you might report some database metrics.
   202  func ExampleMeter_observableUpDownCounter() {
   203  	// The function registers asynchronous metrics for the provided db.
   204  	// Make sure to unregister metric.Registration before closing the provided db.
   205  	_ = func(db *sql.DB, meter metric.Meter, poolName string) (metric.Registration, error) {
   206  		max, err := meter.Int64ObservableUpDownCounter(
   207  			"db.client.connections.max",
   208  			metric.WithDescription("The maximum number of open connections allowed."),
   209  			metric.WithUnit("{connection}"),
   210  		)
   211  		if err != nil {
   212  			return nil, err
   213  		}
   214  
   215  		waitTime, err := meter.Int64ObservableUpDownCounter(
   216  			"db.client.connections.wait_time",
   217  			metric.WithDescription("The time it took to obtain an open connection from the pool."),
   218  			metric.WithUnit("ms"),
   219  		)
   220  		if err != nil {
   221  			return nil, err
   222  		}
   223  
   224  		reg, err := meter.RegisterCallback(
   225  			func(_ context.Context, o metric.Observer) error {
   226  				stats := db.Stats()
   227  				o.ObserveInt64(max, int64(stats.MaxOpenConnections))
   228  				o.ObserveInt64(waitTime, int64(stats.WaitDuration))
   229  				return nil
   230  			},
   231  			max,
   232  			waitTime,
   233  		)
   234  		if err != nil {
   235  			return nil, err
   236  		}
   237  		return reg, nil
   238  	}
   239  }
   240  
   241  // Observable Gauges should be used to measure non-additive values.
   242  //
   243  // Here's how you might report memory usage of the heap objects used
   244  // in application.
   245  func ExampleMeter_observableGauge() {
   246  	if _, err := meter.Int64ObservableGauge(
   247  		"memory.heap",
   248  		metric.WithDescription(
   249  			"Memory usage of the allocated heap objects.",
   250  		),
   251  		metric.WithUnit("By"),
   252  		metric.WithInt64Callback(func(_ context.Context, o metric.Int64Observer) error {
   253  			var m runtime.MemStats
   254  			runtime.ReadMemStats(&m)
   255  			o.Observe(int64(m.HeapAlloc))
   256  			return nil
   257  		}),
   258  	); err != nil {
   259  		panic(err)
   260  	}
   261  }
   262  
   263  // You can add Attributes by using the [WithAttributeSet] and [WithAttributes] options.
   264  //
   265  // Here's how you might add the HTTP status code attribute to your recordings.
   266  func ExampleMeter_attributes() {
   267  	apiCounter, err := meter.Int64UpDownCounter(
   268  		"api.finished.counter",
   269  		metric.WithDescription("Number of finished API calls."),
   270  		metric.WithUnit("{call}"),
   271  	)
   272  	if err != nil {
   273  		panic(err)
   274  	}
   275  	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
   276  		// do some work in an API call and set the response HTTP status code
   277  		statusCode := http.StatusOK
   278  
   279  		apiCounter.Add(r.Context(), 1,
   280  			metric.WithAttributes(semconv.HTTPStatusCode(statusCode)))
   281  	})
   282  }
   283
View as plain text