You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Go does not support truly automatic instrumentation like other languages today. Instead, you'll need to depend on [instrumentation libraries](/docs/reference/specification/glossary/#instrumentation-library) that generate telemetry data for a particular instrumented library. For example, the instrumentation library for `net/http` will automatically create spans that track inbound and outbound requests once you configure it in your code.
10
+
Go does not support truly automatic instrumentation like other languages today.
that generate telemetry data for a particular instrumented library. For example,
14
+
the instrumentation library for `net/http` will automatically create spans that
15
+
track inbound and outbound requests once you configure it in your code.
9
16
10
17
## Setup
11
18
12
-
Each instrumentation library is a package. In general, this means you need to `go get` the appropriate package:
19
+
Each instrumentation library is a package. In general, this means you need to
20
+
`go get` the appropriate package:
13
21
14
-
```console
22
+
```sh
15
23
go get go.opentelemetry.io/contrib/instrumentation/{import-path}/otel{package-name}
16
24
```
17
25
18
-
And then configure it in your code based on what the library requires to be activated.
26
+
And then configure it in your code based on what the library requires to be
27
+
activated.
19
28
20
29
## Example with `net/http`
21
30
22
-
As an example, here's how you can set up automatic instrumentation for inbound HTTP requests for `net/http`:
31
+
As an example, here's how you can set up automatic instrumentation for inbound
32
+
HTTP requests for `net/http`:
23
33
24
34
First, get the `net/http` instrumentation library:
25
35
26
-
```console
36
+
```sh
27
37
go get go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp
28
38
```
29
39
@@ -76,13 +86,18 @@ func main() {
76
86
}
77
87
```
78
88
79
-
Assuming that you have a `Tracer` and [exporter]({{< relref "exporters" >}}) configured, this code will:
89
+
Assuming that you have a `Tracer` and [exporter](../exporters/) configured, this
90
+
code will:
80
91
81
-
* Start an HTTP server on port `3030`
82
-
* Automatically generate a span for each inbound HTTP request to `/hello-instrumented`
83
-
* Create a child span of the automatically-generated one that tracks the work done in `sleepy`
92
+
- Start an HTTP server on port `3030`
93
+
- Automatically generate a span for each inbound HTTP request to
94
+
`/hello-instrumented`
95
+
- Create a child span of the automatically-generated one that tracks the work
96
+
done in `sleepy`
84
97
85
-
Connecting manual instrumentation you write in your app with instrumentation generated from a library is essential to get good observability into your apps and services.
98
+
Connecting manual instrumentation you write in your app with instrumentation
99
+
generated from a library is essential to get good observability into your apps
100
+
and services.
86
101
87
102
## Available packages
88
103
@@ -91,6 +106,9 @@ A full list of instrumentation libraries available can be found in the
91
106
92
107
## Next steps
93
108
94
-
Instrumentation libraries can do things like generate telemetry data for inbound and outbound HTTP requests, but they don't instrument your actual application.
109
+
Instrumentation libraries can do things like generate telemetry data for inbound
110
+
and outbound HTTP requests, but they don't instrument your actual application.
95
111
96
-
To get richer telemetry data, use [manual instrumentation]({{< relref "manual" >}}) to enrich your telemetry data from instrumentation libraries with instrumentation from your running application.
112
+
To get richer telemetry data, use [manual instrumentation](../manual/) to enrich
113
+
your telemetry data from instrumentation libraries with instrumentation from
Instrumentation is the process of adding observability code to your application. There are two general types of instrumentation - automatic, and manual - and you should be familiar with both in order to effectively instrument your software.
10
+
Instrumentation is the process of adding observability code to your application.
11
+
There are two general types of instrumentation - automatic, and manual - and you
12
+
should be familiar with both in order to effectively instrument your software.
9
13
10
14
## Getting a Tracer
11
15
@@ -15,7 +19,7 @@ To create spans, you'll need to acquire or initialize a tracer first.
@@ -90,9 +94,12 @@ You can now access `tracer` to manually instrument your code.
90
94
91
95
## Creating Spans
92
96
93
-
Spans are created by tracers. If you don't have one initialized, you'll need to do that.
97
+
Spans are created by tracers. If you don't have one initialized, you'll need to
98
+
do that.
94
99
95
-
To create a span with a tracer, you'll also need a handle on a `context.Context` instance. These will typically come from things like a request object and may already contain a parent span from an [instrumentation library][].
100
+
To create a span with a tracer, you'll also need a handle on a `context.Context`
101
+
instance. These will typically come from things like a request object and may
102
+
already contain a parent span from an [instrumentation library][].
96
103
97
104
```go
98
105
funchttpHandler(whttp.ResponseWriter, r *http.Request) {
@@ -103,13 +110,16 @@ func httpHandler(w http.ResponseWriter, r *http.Request) {
103
110
}
104
111
```
105
112
106
-
In Go, the `context` package is used to store the active span. When you start a span, you'll get a handle on not only the span that's created, but the modified context that contains it.
113
+
In Go, the `context` package is used to store the active span. When you start a
114
+
span, you'll get a handle on not only the span that's created, but the modified
115
+
context that contains it.
107
116
108
117
Once a span has completed, it is immutable and can no longer be modified.
109
118
110
119
### Get the current span
111
120
112
-
To get the current span, you'll need to pull it out of a `context.Context` you have a handle on:
121
+
To get the current span, you'll need to pull it out of a `context.Context` you
122
+
have a handle on:
113
123
114
124
```go
115
125
// This context needs contain the active span you plan to extract.
// Do something with the current span, optionally calling `span.End()` if you want it to end
120
130
```
121
131
122
-
This can be helpful if you'd like to add information to the current span at a point in time.
132
+
This can be helpful if you'd like to add information to the current span at a
133
+
point in time.
123
134
124
135
### Create nested spans
125
136
126
137
You can create a nested span to track work in a nested operation.
127
138
128
-
If the current `context.Context` you have a handle on already contains a span inside of it, creating a new span makes it a nested span. For example:
139
+
If the current `context.Context` you have a handle on already contains a span
140
+
inside of it, creating a new span makes it a nested span. For example:
129
141
130
142
```go
131
143
funcparentFunction(ctxcontext.Context) {
@@ -151,7 +163,10 @@ Once a span has completed, it is immutable and can no longer be modified.
151
163
152
164
### Span Attributes
153
165
154
-
Attributes are keys and values that are applied as metadata to your spans and are useful for aggregating, filtering, and grouping traces. Attributes can be added at span creation, or at any other time during the lifecycle of a span before it has completed.
166
+
Attributes are keys and values that are applied as metadata to your spans and
167
+
are useful for aggregating, filtering, and grouping traces. Attributes can be
168
+
added at span creation, or at any other time during the lifecycle of a span
Semantic Attributes are attributes that are defined by the [OpenTelemetry Specification][] in order to provide a shared set of attribute keys across multiple languages, frameworks, and runtimes for common concepts like HTTP methods, status codes, user agents, and more. These attributes are available in the `go.opentelemetry.io/otel/semconv/v1.12.0` package.
187
+
Semantic Attributes are attributes that are defined by the [OpenTelemetry
188
+
Specification][] in order to provide a shared set of attribute keys across
189
+
multiple languages, frameworks, and runtimes for common concepts like HTTP
190
+
methods, status codes, user agents, and more. These attributes are available in
191
+
the `go.opentelemetry.io/otel/semconv/v1.12.0` package.
173
192
174
193
For details, see [Trace semantic conventions][].
175
194
176
195
### Events
177
196
178
-
An event is a human-readable message on a span that represents "something happening" during it's lifetime. For example, imagine a function that requires exclusive access to a resource that is under a mutex. An event could be created at two points - once, when we try to gain access to the resource, and another when we acquire the mutex.
197
+
An event is a human-readable message on a span that represents "something
198
+
happening" during it's lifetime. For example, imagine a function that requires
199
+
exclusive access to a resource that is under a mutex. An event could be created
200
+
at two points - once, when we try to gain access to the resource, and another
201
+
when we acquire the mutex.
179
202
180
203
```go
181
204
span.AddEvent("Acquiring lock")
@@ -186,7 +209,9 @@ span.AddEvent("Unlocking")
186
209
mutex.Unlock()
187
210
```
188
211
189
-
A useful characteristic of events is that their timestamps are displayed as offsets from the beginning of the span, allowing you to easily see how much time elapsed between them.
212
+
A useful characteristic of events is that their timestamps are displayed as
213
+
offsets from the beginning of the span, allowing you to easily see how much time
214
+
elapsed between them.
190
215
191
216
Events can also have attributes of their own -
192
217
@@ -196,7 +221,8 @@ span.AddEvent("Cancelled wait due to external signal", trace.WithAttributes(attr
196
221
197
222
### Set span status
198
223
199
-
A status can be set on a span, typically used to specify that there was an error in the operation a span is tracking - .`Error`.
224
+
A status can be set on a span, typically used to specify that there was an error
225
+
in the operation a span is tracking - .`Error`.
200
226
201
227
```go
202
228
import (
@@ -213,11 +239,13 @@ if err != nil {
213
239
}
214
240
```
215
241
216
-
By default, the status for all spans is `Unset`. In rare cases, you may also wish to set the status to `Ok`. This should generally not be necessary, though.
242
+
By default, the status for all spans is `Unset`. In rare cases, you may also
243
+
wish to set the status to `Ok`. This should generally not be necessary, though.
217
244
218
245
### Record errors
219
246
220
-
If you have an operation that failed and you wish to capture the error it produced, you can record that error.
247
+
If you have an operation that failed and you wish to capture the error it
248
+
produced, you can record that error.
221
249
222
250
```go
223
251
import (
@@ -235,18 +263,22 @@ if err != nil {
235
263
}
236
264
```
237
265
238
-
It is highly recommended that you also set a span's status to `Error` when using `RecordError`, unless you do not wish to consider the span tracking a failed operation as an error span.
239
-
The `RecordError` function does **not** automatically set a span status when called.
266
+
It is highly recommended that you also set a span's status to `Error` when using
267
+
`RecordError`, unless you do not wish to consider the span tracking a failed
268
+
operation as an error span. The `RecordError` function does **not**
269
+
automatically set a span status when called.
240
270
241
271
## Creating Metrics
242
272
243
273
The metrics API is currently unstable, documentation TBA.
244
274
245
275
## Propagators and Context
246
276
247
-
Traces can extend beyond a single process. This requires _context propagation_, a mechanism where identifiers for a trace are sent to remote processes.
277
+
Traces can extend beyond a single process. This requires _context propagation_,
278
+
a mechanism where identifiers for a trace are sent to remote processes.
248
279
249
-
In order to propagate trace context over the wire, a propagator must be registered with the OpenTelemetry API.
280
+
In order to propagate trace context over the wire, a propagator must be
> OpenTelemetry also supports the B3 header format, for compatibility with existing tracing systems (`go.opentelemetry.io/contrib/propagators/b3`) that do not support the W3C TraceContext standard.
292
+
> OpenTelemetry also supports the B3 header format, for compatibility with
293
+
> existing tracing systems (`go.opentelemetry.io/contrib/propagators/b3`) that
294
+
> do not support the W3C TraceContext standard.
261
295
262
-
After configuring context propagation, you'll most likely want to use automatic instrumentation to handle the behind-the-scenes work of actually managing serializing the context.
296
+
After configuring context propagation, you'll most likely want to use automatic
297
+
instrumentation to handle the behind-the-scenes work of actually managing
0 commit comments