OpenTelemetry

Endpoint

otel

URL

https://${OBSERVE_CUSTOMER}.collect.observeinc.com/v2/otel

Maximum Request Size (compressed)

10 MB

Maximum Request Size (uncompressed)

50 MB

Individual Metric, Span, or Event Limit (including attributes and resource attributes)

1 MB

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.

The request body should be encoded in the Protobuf format and sent with the content-type application/x-protobuf (specs). JSON encoding using application/json content-type are also supported (specs).

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.

[!CAUTION] (Exponential) Histograms with cummulative aggregation are not currently supported! Data will be stored but quantile calculations will be wrong.

[!WARNING] 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