openapi: 3.1.0
info:
title: OpenTelemetry Protocol (OTLP) HTTP API
description: >-
The OpenTelemetry Protocol (OTLP) HTTP API provides endpoints for
receiving telemetry data including traces, metrics, and logs. OTLP is
the native protocol for OpenTelemetry and defines how telemetry data
is encoded, transported, and delivered between telemetry sources,
collectors, and backends.
version: 1.0.0
contact:
name: OpenTelemetry
url: https://opentelemetry.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:4318
description: Default OTLP HTTP receiver endpoint
paths:
/v1/traces:
post:
operationId: exportTraces
summary: OpenTelemetry Export trace data
description: >-
Accepts a batch of spans encoded in OTLP format. Each span
represents a unit of work or operation within a distributed
trace, containing timing data, attributes, events, and links.
tags:
- Traces
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExportTraceServiceRequest'
application/x-protobuf:
schema:
type: string
format: binary
responses:
'200':
description: Successfully accepted trace data
content:
application/json:
schema:
$ref: '#/components/schemas/ExportTraceServiceResponse'
'400':
description: Bad request - malformed payload
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'429':
description: Too many requests - rate limited
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'503':
description: Service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/metrics:
post:
operationId: exportMetrics
summary: OpenTelemetry Export metric data
description: >-
Accepts a batch of metrics encoded in OTLP format. Metrics
represent measurements captured at runtime, including gauges,
sums, histograms, and summaries with associated resource and
instrumentation scope metadata.
tags:
- Metrics
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExportMetricsServiceRequest'
application/x-protobuf:
schema:
type: string
format: binary
responses:
'200':
description: Successfully accepted metric data
content:
application/json:
schema:
$ref: '#/components/schemas/ExportMetricsServiceResponse'
'400':
description: Bad request - malformed payload
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'429':
description: Too many requests - rate limited
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'503':
description: Service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
/v1/logs:
post:
operationId: exportLogs
summary: OpenTelemetry Export log data
description: >-
Accepts a batch of log records encoded in OTLP format. Log
records represent timestamped text or structured data entries
with severity levels, associated resource metadata, and
optional trace context for correlation.
tags:
- Logs
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExportLogsServiceRequest'
application/x-protobuf:
schema:
type: string
format: binary
responses:
'200':
description: Successfully accepted log data
content:
application/json:
schema:
$ref: '#/components/schemas/ExportLogsServiceResponse'
'400':
description: Bad request - malformed payload
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'429':
description: Too many requests - rate limited
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'503':
description: Service unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
components:
schemas:
ExportTraceServiceRequest:
type: object
description: Request message for the trace export service
properties:
resourceSpans:
type: array
description: Batch of resource spans
items:
$ref: '#/components/schemas/ResourceSpans'
ExportTraceServiceResponse:
type: object
description: Response message for the trace export service
properties:
partialSuccess:
$ref: '#/components/schemas/ExportTracePartialSuccess'
ExportTracePartialSuccess:
type: object
description: Indicates partial success when some spans were rejected
properties:
rejectedSpans:
type: integer
format: int64
description: Number of spans rejected
errorMessage:
type: string
description: Human-readable error message
ExportMetricsServiceRequest:
type: object
description: Request message for the metrics export service
properties:
resourceMetrics:
type: array
description: Batch of resource metrics
items:
$ref: '#/components/schemas/ResourceMetrics'
ExportMetricsServiceResponse:
type: object
description: Response message for the metrics export service
properties:
partialSuccess:
$ref: '#/components/schemas/ExportMetricsPartialSuccess'
ExportMetricsPartialSuccess:
type: object
description: Indicates partial success when some data points were rejected
properties:
rejectedDataPoints:
type: integer
format: int64
description: Number of data points rejected
errorMessage:
type: string
description: Human-readable error message
ExportLogsServiceRequest:
type: object
description: Request message for the logs export service
properties:
resourceLogs:
type: array
description: Batch of resource logs
items:
$ref: '#/components/schemas/ResourceLogs'
ExportLogsServiceResponse:
type: object
description: Response message for the logs export service
properties:
partialSuccess:
$ref: '#/components/schemas/ExportLogsPartialSuccess'
ExportLogsPartialSuccess:
type: object
description: Indicates partial success when some log records were rejected
properties:
rejectedLogRecords:
type: integer
format: int64
description: Number of log records rejected
errorMessage:
type: string
description: Human-readable error message
ResourceSpans:
type: object
description: Collection of spans from a resource
properties:
resource:
$ref: '#/components/schemas/Resource'
scopeSpans:
type: array
description: Spans grouped by instrumentation scope
items:
$ref: '#/components/schemas/ScopeSpans'
schemaUrl:
type: string
description: Schema URL for the resource
ScopeSpans:
type: object
description: Spans associated with an instrumentation scope
properties:
scope:
$ref: '#/components/schemas/InstrumentationScope'
spans:
type: array
description: List of spans
items:
$ref: '#/components/schemas/Span'
schemaUrl:
type: string
description: Schema URL for the instrumentation scope
Span:
type: object
description: >-
A span represents a single operation within a trace. Spans can
be nested to form a trace tree. Each span has a name, timing
data, structured log messages (events), and links to other spans.
required:
- traceId
- spanId
- name
- kind
- startTimeUnixNano
- endTimeUnixNano
properties:
traceId:
type: string
description: Unique 16-byte trace identifier as 32 hex characters
pattern: ^[a-f0-9]{32}$
spanId:
type: string
description: Unique 8-byte span identifier as 16 hex characters
pattern: ^[a-f0-9]{16}$
traceState:
type: string
description: W3C trace state header value
parentSpanId:
type: string
description: Span ID of the parent span (empty for root spans)
pattern: ^[a-f0-9]{16}$
flags:
type: integer
format: int32
description: Trace flags as defined in W3C Trace Context
name:
type: string
description: Human-readable name of the span
kind:
type: integer
description: >-
Span kind: 0=unspecified, 1=internal, 2=server, 3=client,
4=producer, 5=consumer
enum: [0, 1, 2, 3, 4, 5]
startTimeUnixNano:
type: string
format: uint64
description: Start time in nanoseconds since Unix epoch
endTimeUnixNano:
type: string
format: uint64
description: End time in nanoseconds since Unix epoch
attributes:
type: array
description: Key-value pairs providing additional span context
items:
$ref: '#/components/schemas/KeyValue'
droppedAttributesCount:
type: integer
format: int32
description: Number of attributes dropped due to limits
events:
type: array
description: Timed events associated with the span
items:
$ref: '#/components/schemas/SpanEvent'
droppedEventsCount:
type: integer
format: int32
description: Number of events dropped due to limits
links:
type: array
description: Links to other spans in the same or different traces
items:
$ref: '#/components/schemas/SpanLink'
droppedLinksCount:
type: integer
format: int32
description: Number of links dropped due to limits
status:
$ref: '#/components/schemas/SpanStatus'
SpanEvent:
type: object
description: A timed event within a span
properties:
timeUnixNano:
type: string
format: uint64
description: Event timestamp in nanoseconds since Unix epoch
name:
type: string
description: Event name
attributes:
type: array
description: Event attributes
items:
$ref: '#/components/schemas/KeyValue'
droppedAttributesCount:
type: integer
format: int32
SpanLink:
type: object
description: A reference from one span to another
properties:
traceId:
type: string
description: Trace ID of the linked span
spanId:
type: string
description: Span ID of the linked span
traceState:
type: string
description: W3C trace state of the linked span
attributes:
type: array
description: Link attributes
items:
$ref: '#/components/schemas/KeyValue'
droppedAttributesCount:
type: integer
format: int32
flags:
type: integer
format: int32
SpanStatus:
type: object
description: Status of the span
properties:
message:
type: string
description: Human-readable status message
code:
type: integer
description: 'Status code: 0=unset, 1=ok, 2=error'
enum: [0, 1, 2]
ResourceMetrics:
type: object
description: Collection of metrics from a resource
properties:
resource:
$ref: '#/components/schemas/Resource'
scopeMetrics:
type: array
description: Metrics grouped by instrumentation scope
items:
$ref: '#/components/schemas/ScopeMetrics'
schemaUrl:
type: string
description: Schema URL for the resource
ScopeMetrics:
type: object
description: Metrics associated with an instrumentation scope
properties:
scope:
$ref: '#/components/schemas/InstrumentationScope'
metrics:
type: array
description: List of metrics
items:
$ref: '#/components/schemas/Metric'
schemaUrl:
type: string
description: Schema URL for the instrumentation scope
Metric:
type: object
description: >-
Represents a single metric with its data points. A metric
contains one of gauge, sum, histogram, exponential histogram,
or summary data.
required:
- name
properties:
name:
type: string
description: Metric name
description:
type: string
description: Metric description
unit:
type: string
description: Metric unit (e.g., ms, bytes, 1)
gauge:
$ref: '#/components/schemas/Gauge'
sum:
$ref: '#/components/schemas/Sum'
histogram:
$ref: '#/components/schemas/Histogram'
exponentialHistogram:
$ref: '#/components/schemas/ExponentialHistogram'
summary:
$ref: '#/components/schemas/Summary'
Gauge:
type: object
description: Gauge metric representing instantaneous values
properties:
dataPoints:
type: array
items:
$ref: '#/components/schemas/NumberDataPoint'
Sum:
type: object
description: Sum metric representing cumulative or delta values
properties:
dataPoints:
type: array
items:
$ref: '#/components/schemas/NumberDataPoint'
aggregationTemporality:
type: integer
description: '0=unspecified, 1=delta, 2=cumulative'
enum: [0, 1, 2]
isMonotonic:
type: boolean
description: Whether the sum is monotonically increasing
Histogram:
type: object
description: Histogram metric with explicit bucket boundaries
properties:
dataPoints:
type: array
items:
$ref: '#/components/schemas/HistogramDataPoint'
aggregationTemporality:
type: integer
enum: [0, 1, 2]
ExponentialHistogram:
type: object
description: Histogram metric with exponential bucket boundaries
properties:
dataPoints:
type: array
items:
$ref: '#/components/schemas/ExponentialHistogramDataPoint'
aggregationTemporality:
type: integer
enum: [0, 1, 2]
Summary:
type: object
description: Summary metric with precomputed quantiles
properties:
dataPoints:
type: array
items:
$ref: '#/components/schemas/SummaryDataPoint'
NumberDataPoint:
type: object
description: A single numeric data point
properties:
attributes:
type: array
items:
$ref: '#/components/schemas/KeyValue'
startTimeUnixNano:
type: string
format: uint64
timeUnixNano:
type: string
format: uint64
asDouble:
type: number
format: double
asInt:
type: string
format: int64
exemplars:
type: array
items:
$ref: '#/components/schemas/Exemplar'
flags:
type: integer
format: int32
HistogramDataPoint:
type: object
description: A single histogram data point
properties:
attributes:
type: array
items:
$ref: '#/components/schemas/KeyValue'
startTimeUnixNano:
type: string
format: uint64
timeUnixNano:
type: string
format: uint64
count:
type: string
format: uint64
sum:
type: number
format: double
bucketCounts:
type: array
items:
type: string
format: uint64
explicitBounds:
type: array
items:
type: number
format: double
exemplars:
type: array
items:
$ref: '#/components/schemas/Exemplar'
flags:
type: integer
format: int32
min:
type: number
format: double
max:
type: number
format: double
ExponentialHistogramDataPoint:
type: object
description: A single exponential histogram data point
properties:
attributes:
type: array
items:
$ref: '#/components/schemas/KeyValue'
startTimeUnixNano:
type: string
format: uint64
timeUnixNano:
type: string
format: uint64
count:
type: string
format: uint64
sum:
type: number
format: double
scale:
type: integer
format: int32
zeroCount:
type: string
format: uint64
positive:
$ref: '#/components/schemas/ExponentialHistogramBuckets'
negative:
$ref: '#/components/schemas/ExponentialHistogramBuckets'
flags:
type: integer
format: int32
exemplars:
type: array
items:
$ref: '#/components/schemas/Exemplar'
min:
type: number
format: double
max:
type: number
format: double
zeroThreshold:
type: number
format: double
ExponentialHistogramBuckets:
type: object
description: Bucket counts for exponential histograms
properties:
offset:
type: integer
format: int32
bucketCounts:
type: array
items:
type: string
format: uint64
SummaryDataPoint:
type: object
description: A single summary data point
properties:
attributes:
type: array
items:
$ref: '#/components/schemas/KeyValue'
startTimeUnixNano:
type: string
format: uint64
timeUnixNano:
type: string
format: uint64
count:
type: string
format: uint64
sum:
type: number
format: double
quantileValues:
type: array
items:
type: object
properties:
quantile:
type: number
format: double
value:
type: number
format: double
flags:
type: integer
format: int32
Exemplar:
type: object
description: Sample input measurement with trace context
properties:
filteredAttributes:
type: array
items:
$ref: '#/components/schemas/KeyValue'
timeUnixNano:
type: string
format: uint64
asDouble:
type: number
format: double
asInt:
type: string
format: int64
spanId:
type: string
traceId:
type: string
ResourceLogs:
type: object
description: Collection of logs from a resource
properties:
resource:
$ref: '#/components/schemas/Resource'
scopeLogs:
type: array
description: Logs grouped by instrumentation scope
items:
$ref: '#/components/schemas/ScopeLogs'
schemaUrl:
type: string
description: Schema URL for the resource
ScopeLogs:
type: object
description: Logs associated with an instrumentation scope
properties:
scope:
$ref: '#/components/schemas/InstrumentationScope'
logRecords:
type: array
description: List of log records
items:
$ref: '#/components/schemas/LogRecord'
schemaUrl:
type: string
description: Schema URL for the instrumentation scope
LogRecord:
type: object
description: >-
A single log record representing a timestamped event with
severity, body content, and associated metadata.
properties:
timeUnixNano:
type: string
format: uint64
description: Log timestamp in nanoseconds since Unix epoch
observedTimeUnixNano:
type: string
format: uint64
description: Time when the log was observed by the collection system
severityNumber:
type: integer
description: Numeric severity value (1-24)
minimum: 1
maximum: 24
severityText:
type: string
description: 'Severity text (e.g., TRACE, DEBUG, INFO, WARN, ERROR, FATAL)'
body:
$ref: '#/components/schemas/AnyValue'
attributes:
type: array
description: Additional log attributes
items:
$ref: '#/components/schemas/KeyValue'
droppedAttributesCount:
type: integer
format: int32
flags:
type: integer
format: int32
description: Trace flags for log-trace correlation
traceId:
type: string
description: Trace ID for correlating logs with traces
spanId:
type: string
description: Span ID for correlating logs with spans
Resource:
type: object
description: >-
Describes the entity producing telemetry. A resource has
attributes such as service.name, service.version, host.name,
and other identifying metadata.
properties:
attributes:
type: array
description: Resource attributes
items:
$ref: '#/components/schemas/KeyValue'
droppedAttributesCount:
type: integer
format: int32
InstrumentationScope:
type: object
description: >-
Metadata about the instrumentation library or component
that produced the telemetry data.
properties:
name:
type: string
description: Instrumentation scope name
version:
type: string
description: Instrumentation scope version
attributes:
type: array
description: Scope attributes
items:
$ref: '#/components/schemas/KeyValue'
droppedAttributesCount:
type: integer
format: int32
KeyValue:
type: object
description: A key-value pair for attributes
required:
- key
- value
properties:
key:
type: string
description: Attribute key
value:
$ref: '#/components/schemas/AnyValue'
AnyValue:
type: object
description: >-
A polymorphic value container that can hold string, bool, int,
double, array, or key-value list values.
properties:
stringValue:
type: string
boolValue:
type: boolean
intValue:
type: string
format: int64
doubleValue:
type: number
format: double
arrayValue:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/AnyValue'
kvlistValue:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/KeyValue'
bytesValue:
type: string
format: byte
Status:
type: object
description: Error status response
properties:
code:
type: integer
description: HTTP status code
message:
type: string
description: Human-readable error message
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication for secured OTLP endpoints
tags:
- name: Logs
- name: Metrics
- name: Traces