Verify metric OTLP exporters compliance with the configuration specification

[MrAlias]

Specification: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.25.0/specification/protocol/exporter.md

Create an issue for anything not compliant.

[MadVikingGod]

Configuration Options

The following configuration options MUST be available to configure the OTLP exporter.
Each configuration option MUST be overridable by a signal specific option.

• Endpoint (OTLP/HTTP):

  • The endpoint MUST be a valid URL with scheme (http or https) and host,
  • The endpoint MAY contain a port,
  • The endpoint SHOULD contain a path
  • The endpoint MUST NOT contain other parts (such as query string or fragment).
  • When using OTEL_EXPORTER_OTLP_ENDPOINT,
    • exporters MUST construct per-signal URLs as described below.
    • Not Normative here, but is by other parts of the spec The per-signal endpoint configuration options take precedence and can be used to override this behavior (the URL is used as-is for them, without any modifications).
  • Not Normative Default: http://localhost:4318
    • SDKs SHOULD default endpoint variables to use http scheme unless they have good reasons to choose https scheme for the default (e.g., for backward compatibility reasons in a stable SDK release).
  • Env vars:
    • OTEL_EXPORTER_OTLP_ENDPOINT
    • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT

• Endpoint (OTLP/gRPC):

  • The endpoint SHOULD accept any form allowed by the underlying gRPC client implementation.
  • The endpoint MUST accept a URL with a scheme of either http or https.
  • If the gRPC client implementation does not support an endpoint with a scheme of http or https then the endpoint SHOULD be transformed to the most sensible format for that implementation.
  • Not Normative Default: http://localhost:4317
    • SDKs SHOULD default endpoint variables to use http scheme unless they have good reasons to choose https scheme for the default (e.g., for backward compatibility reasons in a stable SDK release).
  • Env vars:
    • OTEL_EXPORTER_OTLP_ENDPOINT
    • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT

• Insecure:

  • Not Normative This option only applies to OTLP/gRPC when an endpoint is provided without the http or https scheme - [ ] OTLP/HTTP always uses the scheme provided for the endpoint.
  • Implementations MAY choose to not implement the insecure option if it is not required or supported by the underlying gRPC client implementation.
  • Not Normative Default: false
  • Env vars:
    • OTEL_EXPORTER_OTLP_INSECURE
    • OTEL_EXPORTER_OTLP_METRICS_INSECURE
    • OTEL_EXPORTER_OTLP_METRIC_INSECURE

• Certificate File:

  • Not Normative Default: n/a
  • Env vars:
    • OTEL_EXPORTER_OTLP_CERTIFICATE
    • OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE

• Client key file:

  • Not Normative Default: n/a
  • Env vars:
    • OTEL_EXPORTER_OTLP_CLIENT_KEY
    • OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY

• Client certificate file:

  • Not Normative Default: n/a
  • Env vars:
    • OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE
    • OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE

• Headers:

  • Not Normative Default: n/a
  • Env vars:
    • OTEL_EXPORTER_OTLP_HEADERS
    • OTEL_EXPORTER_OTLP_METRICS_HEADERS

• Compression:

  • Not Normative Supported compression: gzip, none.
  • Not Normative Default: No value [2]
  • Not Normative If no compression value is explicitly specified, SIGs can default to the value they deem most useful among the supported options
  • Env vars:
    • OTEL_EXPORTER_OTLP_COMPRESSION
    • OTEL_EXPORTER_OTLP_METRICS_COMPRESSION

• Timeout:

  • Not Normative Default: 10s
  • Env vars:
    • OTEL_EXPORTER_OTLP_TIMEOUT
    • OTEL_EXPORTER_OTLP_METRICS_TIMEOUT

• Protocol:

  • Options MUST be one of: grpc, http/protobuf, http/json.
  • Not Normative Default: http/protobuf [3]
  • Env vars:
    • OTEL_EXPORTER_OTLP_PROTOCOL
    • OTEL_EXPORTER_OTLP_METRICS_PROTOCOL

[MadVikingGod]

Endpoint URLs for OTLP/HTTP

• Based on the environment variables above, the OTLP/HTTP exporter MUST construct URLs for each signal as follow:

  • For the per-signal variables (OTEL_EXPORTER_OTLP__ENDPOINT), the URL MUST be used as-is without any modification.
  • If an URL contains no path part, the root path / MUST be used.
  • If OTEL_EXPORTER_OTLP_ENDPOINT is used path should be `v1/metrics``.

• An SDK MUST NOT modify the URL in ways other than specified above.

• If the port is empty or not given,

  • TCP port 80 is the default for the http scheme
  • TCP port 443 is the default for the https scheme

Specify Protocol

• SDKs SHOULD support both grpc and http/protobuf transports
• SDKs MUST support one of grpc and http/protobuf transports
• If they support only one, it SHOULD be http/protobuf.
• SDKs MAY support http/json.
• If no configuration is provided the default transport SHOULD be http/protobuf

Specifying headers via environment variables

• All attribute values MUST be considered strings.

Retry

• Transient errors MUST be handled with a retry strategy.
• The retry strategy MUST implement an exponential back-off with jitter.

Transient errors

• Transient errors are defined by the OTLP protocol specification.
• For OTLP/gRPC, transient errors are defined by a set of retryable gRPC status codes.
• For OTLP/HTTP, transient errors are defined by:
  • A set of retryable HTTP status codes received from the server.
  • The scenarios described in: All other responses and OTLP/HTTP Connection.

User Agent

• OpenTelemetry protocol exporters SHOULD emit a User-Agent header to at a minimum identify the exporter, the language of its implementation, and the version of the exporter.
• The format of the header SHOULD follow RFC 7231.

[pellared]

Blocked by:

• Clarify if OTEL_EXPORTER_OTLP_SPAN_INSECURE and OTEL_EXPORTER_OTLP_METRIC_INSECURE are required for new implementation opentelemetry-specification#3717
  • OTEL_EXPORTER_OTLP_SPAN_INSECURE and OTEL_EXPORTER_OTLP_METRIC_INSECURE are not required for new implementations opentelemetry-specification#3719
• Clarify if the OTLP exporter has to support all protocol related env vars opentelemetry-specification#3721
  • Define OTLP protocol driver registration mechanism opentelemetry-specification#3722
  • otlpmetric: Support OTEL_EXPORTER_OTLP_PROTOCOL and OTEL_EXPORTER_OTLP_METRICS_PROTOCOL environmental variables #4641
  • protocol/exporter: Configuration options MAY be implemented by exporter, SDK, or separate component opentelemetry-specification#3730
• OTLP exporters have improper default endpoint  #4147
• OTEL_EXPORTER_OTLP_ENDPOINT MUST NOT contain other query string or fragment #4646
  • Clarify OTLP/HTTP endpoint configuration option handling opentelemetry-specification#3739
• otlptracegrpc otlpmetricgrpc: Handling RESOURCE_EXHAUSTED #4661
• otlptracehttp otlpmetrichttp: Handling 502 Bad Gateway and 504 Gateway Timeout #4662
• otlptracehttp otlpmetrichttp: Handling errors and retries for HTTP requests #4663

Side note: most of the issues are related to the error handling and the OTLP trace exporter is affected by the same issues.

[pellared]

All issues solved. Closing.