OpenTelemetry
Accepts OpenTelemetry(OTel) GRPC or HTTPS directly to your pipeline's ingest endpoint.
Requirements
There are no Prerequisites to start using the OTel input. Simply create an OTel Input and attach it to a pipeline.
Details
The OTel input is meant to be a flexible endpoint that one can point their implementation to, to have traces, logs, and metrics collected.
Sending data
Every pipeline has its own ingest host. Point your exporter at it and send with an API key:
Code
Replace <pipeline-id> with the ID of your pipeline.
The endpoints accept:
- HTTPS JSON (port 4318)
- HTTPS Protobuf (port 4318)
- GRPC (port 4317)
Each OTel object will be converted to its JSON representation and sent to the stream exactly as it is provided, regardless of input method.
Self-hosted deployments
A per-pipeline ingest host needs the *.data.<your Monad domain> wildcard in place: a DNS record plus a matching certificate SAN. Monad Cloud has this. A self-hosted deployment has it only if whoever installed Monad set it up, so check with them if you are not sure. See Customer Helm Install for the setup.
Without it, point the exporter at your own Monad hostname (https://<your-monad-host>:4318 for OTLP/HTTP, :4317 for gRPC) and name the pipeline with a header instead: Monad-Pipeline-Id: <pipeline-id>, or the lower-case monad-pipeline-id metadata key for gRPC. Everything else, including the API key, is the same.
Authentication
All requests to the OTel input endpoint require authentication using an organization API key with the pipeline:data:write permission.
API Key Requirements
The API key must meet the following requirements:
- Must be an organization API key (not a personal API key)
- Must have the
pipeline:data:writepermission, which is included by default in the following roles:- Contributor
- System Administrator
- Alternatively, the permission can be added to a custom role
Required Headers
You must include an authentication header:
- Authorization:
ApiKey <API_KEY>
The ingest host already names the pipeline, so no pipeline ID header is needed. Monad reads it from the Host header for HTTPS and from the gRPC :authority pseudo-header. If you do send a pipeline ID as well, as the Monad-Pipeline-Id HTTP header or the monad-pipeline-id GRPC metadata key, it has to name the same pipeline as the host, so one pipeline's host cannot be used to write to another.
For information on how to use envvars to set OTel headers in standards compliant ways, see this OTLP exporter guide
The Content-Type header is required, and is used to determine handling. This should be set by your OTel implementation automatically.
Example OTLP Settings
Code
Response Examples
Success Response (200)
The response received depends on the method used to send.
JSON and protobuf will respond with an HTTP 200 with body
Code
GRPC will respond with a compliant success response.
Error Responses
Below are some common errors. Others may occur depending on differing error conditions.
| Response | Description |
|---|---|
authorization required | No authentication header was provided |
invalid JWT | The provided JWT token is invalid |
failed to get api key | The API key is no longer valid |
access denied: this endpoint requires pipeline:data:write | The API key lacks the required pipeline:data:write permission |
host does not name a pipeline | The first label of the ingest host is not a pipeline ID |
pipeline id does not match the ingest host | A Monad-Pipeline-Id header (or monad-pipeline-id metadata) named a different pipeline than the host |
An item of this type does not exist. | The provided pipeline ID does not exist |
pipeline not found or not an OTel input | The pipeline exists but is not configured as an OTel input |
Sync frequency
This is a push (receiver) input: Monad ingests records as the source sends them, so there is no polling interval. See Input Sync Frequency for details.