import SelfHostedOtelEndpoint from "../../../partials/ingest/self-hosted-otel-endpoint.mdx";

# 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:

```
https://<pipeline-id>.data.monad.com:4318   # HTTPS
https://<pipeline-id>.data.monad.com:4317   # GRPC
```

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.

<SelfHostedOtelEndpoint />

## 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:write` permission, 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](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/)

The `Content-Type` header is required, and is used to determine handling.  This should be set by your OTel implementation automatically.

## Example OTLP Settings

```
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<pipeline-id>.data.monad.com:4317
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey <yourkey>"
```

## 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 
```json
{
  "code": 0,
  "message": "OK"
}
```

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](../../guides/sync-frequency) for details.