diff --git a/website_docs/exporting_data.md b/website_docs/exporting_data.md index 962b6da0972..8b468eed8c1 100644 --- a/website_docs/exporting_data.md +++ b/website_docs/exporting_data.md @@ -13,7 +13,7 @@ A sampler needs to be set on the tracer provider when its configured, as follows ```go provider := sdktrace.NewTracerProvider( - sdktrace.WithConfig(sdktrace.Config{DefaultSampler: sdktrace.AlwaysSample()}), + sdktrace.WithSampler(sdktrace.AlwaysSample()), ) ``` @@ -24,6 +24,8 @@ Other samplers include: * `TraceIDRatioBased`, which will sample a fraction of traces, based on the fraction given to the sampler. Thus, if you set this to .5, half of traces will be sampled. * `ParentBased`, which behaves differently based on the incoming sampling decision. In general, this will sample spans that have parents that were sampled, and will not sample spans whose parents were _not_ sampled. +When you're in production, you should consider using the `TraceIDRatioBased` sampler with the `ParentBased` samler. + # Resources Resources are a special type of attribute that apply to all spans generated by a process. These should be used to represent underlying metadata about a process that's non-ephemeral - for example, the hostname of a process, or its instance ID. @@ -32,9 +34,9 @@ Resources should be assigned to a tracer provider at its initialization, and are ```go resources := resource.New( - label.String("service.name", "myService"), - label.String("service.version", "1.0.0"), - label.String("instance.id", "abcdef12345"), + attribute.String("service.name", "myService"), + attribute.String("service.version", "1.0.0"), + attribute.String("instance.id", "abcdef12345"), ) provider := sdktrace.NewTracerProvider( diff --git a/website_docs/getting-started.md b/website_docs/getting-started.md index d9394d8742a..46f1878cdd6 100644 --- a/website_docs/getting-started.md +++ b/website_docs/getting-started.md @@ -15,7 +15,7 @@ To get started with this guide, create a new directory and add a new file named To install the necessary prerequisites for OpenTelemetry, you'll want to run the following command in the directory with your `go.mod`: -`go get go.opentelemetry.io/otel@v0.16.0 go.opentelemetry.io/otel/sdk@v0.16.0 go.opentelemetry.io/otel/exporters/stdout@v0.16.0` +`go get go.opentelemetry.io/otel@v0.20.0 go.opentelemetry.io/otel/sdk@v0.20.0 go.opentelemetry.io/otel/exporters/stdout@v0.20.0` In your `main.go` file, you'll need to import several packages: @@ -30,7 +30,7 @@ import ( "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/baggage" "go.opentelemetry.io/otel/exporters/stdout" - "go.opentelemetry.io/otel/label" + "go.opentelemetry.io/otel/attribute" "go.opentelemetry.io/otel/metric" "go.opentelemetry.io/otel/propagation" controller "go.opentelemetry.io/otel/sdk/metric/controller/basic" @@ -128,22 +128,22 @@ It's important to note that if you do not set a propagator, the default is to us The next step is to create metric instruments that will capture measurements. There are two kinds of instruments: synchronous and asynchronous. Synchronous instruments capture measurements by explicitly calling the capture either by the application or by an instrumented library. Depending on the semantics of the measurements, we can say that synchronous instruments record or add measurements. Asynchronous instruments provide a callback that captures measurements. The callback is periodically called by meter in the background. We can say that asynchronous instrument performs observations. -Each measurement can be associated with labels that can later be used by visualisation software to categorize and filter measurements. In case of synchronous instruments the labels can be passed at the moment of capturing a measurement or can be passed when binding the instrument. Such a bound instrument can be later used to capture measurements without passing the labels. In case of asynchronous instruments, the labels are passed each time an observation is made explicitly in the callback. +Each measurement can be associated with attributes that can later be used by visualisation software to categorize and filter measurements. In case of synchronous instruments the attributes can be passed at the moment of capturing a measurement or can be passed when binding the instrument. Such a bound instrument can be later used to capture measurements without passing the attributes. In case of asynchronous instruments, the attributes are passed each time an observation is made explicitly in the callback. To set up some metric instruments, add the following code to your `main.go` file - ```go - fooKey := label.Key("ex.com/foo") - barKey := label.Key("ex.com/bar") - lemonsKey := label.Key("ex.com/lemons") - anotherKey := label.Key("ex.com/another") + fooKey := attribute.Key("ex.com/foo") + barKey := attribute.Key("ex.com/bar") + lemonsKey := attribute.Key("ex.com/lemons") + anotherKey := attribute.Key("ex.com/another") - commonLabels := []label.KeyValue{lemonsKey.Int(10), label.String("A", "1"), label.String("B", "2"), label.String("C", "3")} + commonAttributes := []attribute.KeyValue{lemonsKey.Int(10), attribute.String("A", "1"), attribute.String("B", "2"), attribute.String("C", "3")} meter := otel.Meter("ex.com/basic") observerCallback := func(_ context.Context, result metric.Float64ObserverResult) { - result.Observe(1, commonLabels...) + result.Observe(1, commonAttributes...) } _ = metric.Must(meter).NewFloat64ValueObserver("ex.com.one", observerCallback, metric.WithDescription("A ValueObserver set to 1.0"), @@ -151,11 +151,11 @@ To set up some metric instruments, add the following code to your `main.go` file valueRecorder := metric.Must(meter).NewFloat64ValueRecorder("ex.com.two") - boundRecorder := valueRecorder.Bind(commonLabels...) + boundRecorder := valueRecorder.Bind(commonAttributes...) defer boundRecorder.Unbind() ``` -In this block we first create some keys and labels that we will later use when capturing the measurements. Then we ask a global meter provider to give us a named meter instance ("ex.com/basic"). This acts as a way to namespace our instruments and make them distinct from other instruments in this process or another. Then we use the meter to create two instruments - an asynchronous value observer and a synchronous value recorder. +In this block we first create some keys and attributes that we will later use when capturing the measurements. Then we ask a global meter provider to give us a named meter instance ("ex.com/basic"). This acts as a way to namespace our instruments and make them distinct from other instruments in this process or another. Then we use the meter to create two instruments - an asynchronous value observer and a synchronous value recorder. # Quick Start @@ -173,13 +173,13 @@ Let's put the concepts we've just covered together, and create a trace and some ctx, span = tracer.Start(ctx, "operation") defer span.End() - span.AddEvent("Nice operation!", trace.WithAttributes(label.Int("bogons", 100))) + span.AddEvent("Nice operation!", trace.WithAttributes(attribute.Int("bogons", 100))) span.SetAttributes(anotherKey.String("yes")) meter.RecordBatch( // Note: call-site variables added as context Entries: baggage.ContextWithValues(ctx, anotherKey.String("xyz")), - commonLabels, + commonAttributes, valueRecorder.Measurement(2.0), ) diff --git a/website_docs/instrumentation.md b/website_docs/instrumentation.md index bbe2fb62b8e..756779f338a 100644 --- a/website_docs/instrumentation.md +++ b/website_docs/instrumentation.md @@ -46,15 +46,15 @@ Attributes are keys and values that are applied as metadata to your spans and ar ```go // setting attributes at creation... -ctx, span = tracer.Start(ctx, "attributesAtCreation", trace.WithAttributes(label.String("hello", "world"))) +ctx, span = tracer.Start(ctx, "attributesAtCreation", trace.WithAttributes(attribute.String("hello", "world"))) // ... and after creation -span.SetAttributes(label.Bool("isTrue", true), label.String("stringAttr", "hi!")) +span.SetAttributes(attribute.Bool("isTrue", true), attribute.String("stringAttr", "hi!")) ``` Attribute keys can be precomputed, as well - ```go -var myKey = label.Key("myCoolAttribute") +var myKey = attribute.Key("myCoolAttribute") span.SetAttributes(myKey.String("a value")) ``` @@ -82,7 +82,7 @@ A useful characteristic of events is that their timestamps are displayed as offs Events can also have attributes of their own - ```go -span.AddEvent("Cancelled wait due to external signal", trace.WithAttributes(label.Int("pid", 4328), label.String("signal", "SIGHUP"))) +span.AddEvent("Cancelled wait due to external signal", trace.WithAttributes(attribute.Int("pid", 4328), attribute.String("signal", "SIGHUP"))) ``` # Creating Metrics