Adding OTLP Exporter #699
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| # OpenTelemetry Protocol Exporter | ||
|
|
||
| This document specifies the configuration options available to the OpenTelemetry Protocol ([OTLP](https://github.com/open-telemetry/oteps/blob/master/text/0035-opentelemetry-protocol.md)) `SpanExporter` and `MetricsExporter` as well as the retry behavior. | ||
|
|
||
| ## Configuration Options | ||
|
|
||
| The configuration options are configurable separately for the `SpanExporter` and the `MetricsExporter`. | ||
|
|
||
| | Configuration Option | Description | Default | Env variable | | ||
| | -------------------- | ------------------------------------------------------------ | ----------------- | ------------------------------------------------------------ | | ||
| | Endpoint | Target to which the exporter is going to send spans or metrics. This MAY be configured to include a path (e.g. `example.com/v1/traces`). | `localhost:55680` | `OTEL_EXPORTER_OTLP_SPAN_ENDPOINT` `OTEL_EXPORTER_OTLP_METRIC_ENDPOINT` | | ||
|
There was a problem hiding this comment. It is not completely clear what happens if the Endpoint does not include the path. Is the default path automatically appended? So if I specify There was a problem hiding this comment. My expectation here is that the value configured is taken verbatim and passed to the OTLP exporter in the different languages. I would not expect a path to be appended. This does raise a good question of whether a default value for http and another for grpc makes sense here. There was a problem hiding this comment. I am not sure I like this approach. We are basically not providing any easy way to use the default port and path (for http transport). The default path for OTLP/HTTP is defined in the spec: https://github.com/open-telemetry/oteps/blob/master/text/0099-otlp-http.md#request I believe we need to design the env variables such that configuration is easy in the most common case and for the uncommon cases it is OK if it is a bit more difficult. The most common case is when I need to specify only the ip address or the hostname of the server and choose the transport. Everything else I expect to be set to the correct defaults. The defaults include the port number and when using otlp/http also the path. For example I would expect the following to result in the destination of If I wanted to override the path I would probably be OK if I need to specify the full URL using a different env variable and in that case I don't need to specify the ENDPOINT and TRANSPORT: There may be other ways to structure this but ultimately I want to make sure the most common case is easy and with the current PR I think we are not achieving that goal. Perhaps it is not possible to achieve what I ask for, so feel free to ignore this comment. |
||
| | Protocol | The protocol used to transmit the data. One of `grpc`,`http/json`,`http/proto`. | `grpc` | `OTEL_EXPORTER_OTLP_SPAN_PROTOCOL` `OTEL_EXPORTER_OTLP_METRIC_PROTOCOL` | | ||
| | Insecure | Whether to enable client transport security for the exporter's `grpc` or `http` connection. | `false` | `OTEL_EXPORTER_OTLP_SPAN_INSECURE` `OTEL_EXPORTER_OTLP_METRIC_INSECURE` | | ||
| | Certificate File | Certificate file for TLS credentials of gRPC client. Should only be used if `insecure` is set to `false`. | n/a | `OTEL_EXPORTER_OTLP_SPAN_CERTIFICATE` `OTEL_EXPORTER_OTLP_METRIC_CERTIFICATE` | | ||
| | Headers | The headers associated with gRPC or HTTP requests. | n/a | `OTEL_EXPORTER_OTLP_SPAN_HEADERS` `OTEL_EXPORTER_OTLP_METRIC_HEADERS` | | ||
| | Compression | Compression key for supported compression types. Supported compression: `gzip`| no compression | `OTEL_EXPORTER_OTLP_SPAN_COMPRESSION` `OTEL_EXPORTER_OTLP_METRIC_COMPRESSION` | | ||
| | Timeout | Max waiting time for the backend to process each spans or metrics batch. | 60s | `OTEL_EXPORTER_OTLP_SPAN_TIMEOUT` `OTEL_EXPORTER_OTLP_METRIC_TIMEOUT` | | ||
|
There was a problem hiding this comment. Some other configuration options are exposed by some exporter implementations. I'm not sure if these are generalizable to implementation in all SDKs, but they're worth considering (if they were previously considered and rejected in this PR, please ignore this comment):
Go also allows configuration of gRPC, which includes the retry limit (amongst other things). |
||
|
|
||
| ## Retry | ||
|
|
||
| [Transient errors](#transient-errors) MUST be handled with a retry strategy. This retry strategy MUST implement an exponential back-off with jitter to avoid overwhelming the destination until the network is restored or the destination has recovered. | ||
|
|
||
| ## Transient Errors | ||
| Transient errors are errors which expect the backend to recover. The following status codes are defined as transient errors: | ||
|
|
||
| | HTTP Status Code | Description | | ||
| | ---------------- | ----------- | | ||
| | 408 | Request Timeout | | ||
| | 5xx | Server Errors | | ||
|
|
||
| | gRPC Status Code | Description | | ||
| | ---------------- | ----------- | | ||
| | 1 | Cancelled | | ||
| | 4 | Deadline Exceeded | | ||
| | 7 | Permission Denied | | ||
| | 8 | Resource Exhausted | | ||
| | 10 | Aborted | | ||
| | 10 | Out of Range | | ||
| | 14 | Unavailable | | ||
| | 15 | Data Loss | | ||
| | 16 | Unauthenticated | | ||
|
|
||
| Additional details on transient errors can be found in [otep-35](https://github.com/open-telemetry/oteps/blob/master/text/0035-opentelemetry-protocol.md#export-response) for gRPC and [otep-99](https://github.com/open-telemetry/oteps/blob/master/text/0099-otlp-http.md#failures) for HTTP | ||
Uh oh!
There was an error while loading. Please reload this page.