OpenTelemetry

Endpoint: /otel
URL: https://${OBSERVE_CUSTOMER}.collect.observeinc.com/v1/otel
Maximum request size (compressed): 10MB
Maximum request size (uncompressed): 50MB
Individual metric, span, or event limit (including attributes and resource attributes): 1MB

Observe implements an OLTP HTTP endpoint at /v2/otel supporting the following observation types:

Type	URL Suffix *	Protocol Status
Traces	`v1/traces`	stable
Metrics	`v1/metrics`	stable
Logs	`v1/logs`	stable

Suffix is for documentation purposes, Otel collecting agents will normally append this automatically for each type. So exporter would be configured for instance for customer id 123456: https://123456.collect.observeinc.com/v2/otel. The agent will automatically append the appropriate suffix for each observation type, resulting in complete endpoints such as https://123456.collect.observeinc.com/v2/otel/v1/logs for logs, https://123456.collect.observeinc.com/v2/otel/v1/metrics for metrics, or https://123456.collect.observeinc.com/v2/otel/v1/traces for traces.

Encode the request body in the Protobuf format and sent with the content-type application/x-protobuf. JSON encoding using application/json content-type is also supported. See Binary Protobuf Encoding in the OTLP specification.

This endpoint does not support GRPC.

Type-specific representations

Following tables illustrate for each Otel type how data is mapped from Otel Protobuf records into Observe source dataset entries.

Common

Common to all types is that we flatten the type-specific Resource and Scope hierarchies, turning any attributes on the resource level (opentelemetry.proto.resource.v1.Resource) into a dedicated resource_attributes field and scope information (opentelemetry.proto.common.v1.InstrumentationScope) into instrumentation_scope.

In addition to Otel specific fields Observe metadata is stored in a common meta column.

Otel Field	Observe Column / Field	Comments
`resource.attributes`	`resource_attributes`	Otel kv list is represented as OPAL object
`scope`	`instrumentation_scope`	data is flattened
	`meta`	Observe specific metadata (e.g. ingest token)

Logs

Below describes mapping of all the fields from LogRecord:

Otel Field	Observe Column / Field	Comments
`time_unix_nano`	`timestamp`
`observed_time_unix_nano`	`timestamp`	if `time_unix_nano` is empty
`body`	`body`	Body is always stored as a string. Non-string values will be converted
`attributes`	`attributes`
`severity_number`	`fields.severity_number`
`severity_text`	`fields.severity_text`
`trace_id`	`fields.trace_id`
`span_id`	`fields.span_id`
`dropped_attributes_count`	`fields.dropped_attributes_count`	Only stored if > 0
`flags`	`fields.flags`	Only stored if > 0

Metrics

Below describes mapping of the fields from Metric or one of the nested classes, depending of the type of the metric:

Otel Field	Observe Column / Field	Comments
`time_unix_nano`	`timestamp`
`start_time_unix_nano`	`fields.start_time`	if present
`name`	`metric`
`description`	`description`
`unit`	`unit`
`data`,`aggregation_temporality`	`type`	gauge -> gauge, sum + agg_temp_delta -> delta, sum + agg_temp_cumulative -> cumulativeCounter, histogram -> histogram, exponentialHistogram -> exponential_histogram, summary -> summary
`value`,`quantile_values`	`value`	for gauge, sum and summary (see comments below for summary)
`explicit_bounds`,`Buckets[]`	`complex_value`	for histogram and exponential histogram, encapsulates all the bucket information. see below comments for min/max/count/sum handling
`attributes`	`attributes`
`aggregation_temporality`	`fields.aggregation_temporality`	Only for histograms, otherwise encoded in type
`dropped_attributes_count`	`fields.dropped_attributes_count`	Only stored if > 0
`flags`	`fields.flags`	Only stored if > 0

"Histogram" and "Exponential Histogram" metrics are represented into multiple "pseudo" metrics similar to Prometheus, with suffixes .sum, .count, .min and .max respectively. The types of .count and .sum will be corresponding to the aggregation temporality whereas .min and .max are always gauge. For .count the nunit will be null.

Similarly, "Summary" metrics are flattened into multiple "pseudo" timeseries, with a quantile attribute indicating the corresponding quantily. Given this and as they are deprecated we recommend to use histograms instead.

❗️
Warning
Histograms with cummulative aggregation are not currently supported! Data will be stored but quantile calculations will be wrong.

🚧
Caution
Exemplares are not currently supported and will be dropped.

Traces

Trace data is stored into 3 different datasets: Span, Span Event and Span Link. This is in order to normalize the data into a more relational form and allow easy access of span events as a standalone log dataset.

Span

Below describes mapping of all the fields from Span except for Event and Link types:

Otel Field	Observe Column / Field	Comments
`start_time_unix_nano`	`start_time`, `duration`	`duration`=`end_time-start_time`
`end_time_unix_nano`	`end_time`, `duration`	`duration`=`end_time-start_time`
`trace_id`	`trace_id`
`span_id`	`span_id`
`parent_span_id`	`parent_span_id`
`name`	`span_name`
`kind`	`span_kind`	enum is resolved into string
`attributes`	`attributes`
`status`	`field.status`	`code` enum is resolved into string
`trace_state`	`fields.trace_state`
`dropped_attributes_count`	`fields.dropped_attributes_count`	Only stored if > 0
`dropped_events_count`	`fields.dropped_events_count`	Only stored if > 0
`dropped_links_count`	`fields.dropped_links_count`	Only stored if > 0
`flags`	`fields.flags`	Only stored if > 0

Span event

Below describes mapping of all the fields from Event plus fields inherited from the parent span:

Otel Field	Observe Column / Field	Comments
`time_unix_nano`	`timestamp`
`Span.trace_id`	`trace_id`	inherited from parent span
`Span.span_id`	`span_id`	inherited from parent span
`name`	`event_name`
`attributes`	`attributes`
`dropped_attributes_count`	`fields.dropped_attributes_count`	Only stored if > 0

Span link

Below describes mapping of all the fields from Link plus fields inherited from the parent span:

Otel Field	Observe Column / Field	Comments
`Span.start_time_unix_nano`	`start_time`	inherited from parent span
`Span.end_time_unix_nano`	`end_time`	inherited from parent span
`Span.trace_id`	`trace_id`	inherited from parent span
`Span.span_id`	`span_id`	inherited from parent span
`trace_id`	`linked_trace_id`	linked trace_ _id
`span_id`	`linked_span_id`	linked span_id
`attributes`	`attributes`
`trace_state`	`fields.trace_state`	trace_state of linked trace
`dropped_attributes_count`	`fields.dropped_attributes_count`	Only stored if > 0
`flags`	`fields.flags`	Only stored if > 0

Updated about 2 months ago