README.md
1# OpenTelemetry Collector Go Exporter
2
3[](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp)
4
5
6This exporter exports OpenTelemetry spans and metrics to the OpenTelemetry Collector.
7
8
9## Installation and Setup
10
11The exporter can be installed using standard `go` functionality.
12
13```bash
14$ go get -u go.opentelemetry.io/otel/exporters/otlp
15```
16
17A new exporter can be created using the `NewExporter` function.
18
19```golang
20package main
21
22import (
23 "log"
24
25 "go.opentelemetry.io/otel/exporters/otlp"
26 "go.opentelemetry.io/otel/sdk/metric/controller/push"
27 "go.opentelemetry.io/otel/sdk/metric/selector/simple"
28 sdktrace "go.opentelemetry.io/otel/sdk/trace"
29)
30
31func main() {
32 exporter, err := otlp.NewExporter() // Configure as needed.
33 if err != nil {
34 log.Fatalf("failed to create exporter: %v", err)
35 }
36 defer func() {
37 err := exporter.Stop()
38 if err != nil {
39 log.Fatalf("failed to stop exporter: %v", err)
40 }
41 }()
42
43 // Note: The exporter can also be used as a Batcher. E.g.
44 // traceProvider, err := sdktrace.NewProvider(
45 // sdktrace.WithBatcher(exporter,
46 // sdktrace.WithBatchTimeout(time.Second*15),
47 // sdktrace.WithMaxExportBatchSize(100),
48 // ),
49 // )
50 traceProvider, err := sdktrace.NewProvider(sdktrace.WithBatcher(exporter))
51 if err != nil {
52 log.Fatal("failed to create trace provider: %v", err)
53 }
54
55 pusher := push.New(simple.NewWithExactDistribution(), exporter)
56 pusher.Start()
57 metricProvider := pusher.Provider()
58
59 // Your code here ...
60}
61```
62
63## Configuration
64
65Configurations options can be specified when creating a new exporter (`NewExporter`).
66
67### `WorkerCount(n uint)`
68
69Sets the number of Goroutines to use when processing telemetry.
70
71
72### `WithInsecure()`
73
74Disables client transport security for the exporter's gRPC connection just like [`grpc.WithInsecure()`](https://pkg.go.dev/google.golang.org/grpc#WithInsecure) does.
75By default, client security is required unless `WithInsecure` is used.
76
77### `WithAddress(addr string)`
78
79Sets the address that the exporter will connect to the collector on.
80The default address the exporter connects to is `localhost:55680`.
81
82### `WithReconnectionPeriod(rp time.Duration)`
83
84Set the delay between connection attempts after failing to connect with the collector.
85
86### `WithCompressor(compressor string)`
87
88Set the compressor for the gRPC client to use when sending requests.
89The compressor used needs to have been registered with `google.golang.org/grpc/encoding` prior to using here.
90This can be done by `encoding.RegisterCompressor`.
91Some compressors auto-register on import, such as gzip, which can be registered by calling `import _ "google.golang.org/grpc/encoding/gzip"`.
92
93### `WithHeaders(headers map[string]string)`
94
95Headers to send with gRPC requests.
96
97### `WithTLSCredentials(creds "google.golang.org/grpc/credentials".TransportCredentials)`
98
99TLS credentials to use when talking to the server.
100
101### `WithGRPCServiceConfig(serviceConfig string)`
102
103The default gRPC service config used when .
104
105By default, the exporter is configured to support [retries](#retries).
106
107```json
108{
109 "methodConfig":[{
110 "name":[
111 { "service":"opentelemetry.proto.collector.metrics.v1.MetricsService" },
112 { "service":"opentelemetry.proto.collector.trace.v1.TraceService" }
113 ],
114 "waitForReady": true,
115 "retryPolicy":{
116 "MaxAttempts":5,
117 "InitialBackoff":"0.3s",
118 "MaxBackoff":"5s",
119 "BackoffMultiplier":2,
120 "RetryableStatusCodes":[
121 "UNAVAILABLE",
122 "CANCELLED",
123 "DEADLINE_EXCEEDED",
124 "RESOURCE_EXHAUSTED",
125 "ABORTED",
126 "OUT_OF_RANGE",
127 "UNAVAILABLE",
128 "DATA_LOSS"
129 ]
130 }
131 }]
132}
133```
134
135### `WithGRPCDialOption(opts ..."google.golang.org/grpc".DialOption)`
136
137Additional `grpc.DialOption` to be used.
138
139These options take precedence over any other set by other parts of the configuration.
140
141## Retries
142
143The exporter will not, by default, retry failed requests to the collector.
144However, it is configured in a way that it can easily be enable.
145
146To enable retries, the `GRPC_GO_RETRY` environment variable needs to be set to `on`. For example,
147
148```
149GRPC_GO_RETRY=on go run .
150```
151
152The [default service config](https://github.com/grpc/proposal/blob/master/A6-client-retries.md) used by default is defined to retry failed requests with exponential backoff (`0.3seconds * (2)^retry`) with [a max of `5` retries](https://github.com/open-telemetry/oteps/blob/be2a3fcbaa417ebbf5845cd485d34fdf0ab4a2a4/text/0035-opentelemetry-protocol.md#export-response)).
153
154These retries are only attempted for reponses that are [deemed "retry-able" by the collector](https://github.com/grpc/proposal/blob/master/A6-client-retries.md#validation-of-retrypolicy).
155
){kind=link}