# OTLP

> Send traces from any backend that speaks OpenTelemetry, with the standard OTLP/HTTP exporter.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/otlp/

For agents: Reference of the OTLP endpoints of the Sypnia HTTP API: parameters, response shapes, examples and errors.

Sypnia accepts traces in the OpenTelemetry protocol over HTTP (OTLP/HTTP). Use it for any backend that has
no Sypnia SDK. Traces only: OTLP logs and metrics are not accepted (logs and custom metrics are
[planned](https://docs.sypnia.com/reference/planned)).

## Configure an exporter

Set the standard OpenTelemetry variables. The exporter adds `/v1/traces` to the endpoint by itself.

`.env`

```bash
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.sypnia.com/v1/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_SERVICE_NAME=shop-api
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=4f2a91c
```

Self-hosted: use `<your base URL>/v1/otlp` as the endpoint.

## How spans become Sypnia data

| OpenTelemetry                                                                                               | Sypnia                                                                                           |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Trace id                                                                                                    | The trace id. A browser request that carried the SDK's `traceparent` header joins the same trace |
| Resource `service.name`                                                                                     | The span's `service`                                                                             |
| Resource `deployment.environment.name` (or the older `deployment.environment`)                              | The environment. Default `production`                                                            |
| Resource `service.version`                                                                                  | The release                                                                                      |
| A server span (`SPAN_KIND_SERVER`) with `http.route`                                                        | One API call in [Performance](https://docs.sypnia.com/api/performance) and the root of the trace |
| A client span with `db.system.name`                                                                         | A database call (`kind: db`)                                                                     |
| A client span with `http.request.method`                                                                    | An outgoing HTTP call (`kind: http`)                                                             |
| Span status `ERROR`, or an `exception` span event                                                           | A failure. An exception with a stack becomes a server-side problem                               |
| Span attribute `session.id` (32 hex), or the `x-sypnia-session` request header read by your instrumentation | Links the trace to a session                                                                     |

Span attributes are stored up to 64 per span, 256 characters per value. The engine drops attributes whose key
contains `authorization`, `cookie`, `password`, `secret` or `token`.

## Export traces

`POST /v1/otlp/v1/traces` \[Engine, Cloud]

The OTLP/HTTP trace endpoint, as the OpenTelemetry specification defines it. The body is an
`ExportTraceServiceRequest`, in protobuf (`application/x-protobuf`) or JSON (`application/json`), optionally
with `Content-Encoding: gzip`. The answer is an `ExportTraceServiceResponse` in the same encoding.

When some spans are refused, the answer is still `200` and `partialSuccess` says how many and why, as the
protocol requires. An exporter must not retry a partial success.

**Authentication:** Ingest key

**Limits**

- Body: 4,000,000 bytes after decompression.
- Spans per request: 2,000. Spans per trace that are kept: 500 (the rest are counted in the trace's `dropped_spans`).

**Request:**

```bash
curl -X POST "https://ingest.sypnia.com/v1/otlp/v1/traces" \
  -H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  --data @spans.json
```

**Request body:**

```json
{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": {
              "stringValue": "shop-api"
            }
          },
          {
            "key": "service.version",
            "value": {
              "stringValue": "4f2a91c"
            }
          },
          {
            "key": "deployment.environment.name",
            "value": {
              "stringValue": "production"
            }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "traceId": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
              "spanId": "a1b2c3d4e5f60718",
              "parentSpanId": "0f1e2d3c4b5a6978",
              "name": "POST /api/checkout",
              "kind": 2,
              "startTimeUnixNano": "1773311503130000000",
              "endTimeUnixNano": "1773311506972000000",
              "attributes": [
                {
                  "key": "http.request.method",
                  "value": {
                    "stringValue": "POST"
                  }
                },
                {
                  "key": "http.route",
                  "value": {
                    "stringValue": "/api/checkout"
                  }
                },
                {
                  "key": "http.response.status_code",
                  "value": {
                    "intValue": "400"
                  }
                }
              ],
              "status": {
                "code": 2
              }
            }
          ]
        }
      ]
    }
  ]
}
```

**Response: Every span stored (200):**

```json
{}
```

**Response: Some spans refused (200):**

```json
{
  "partialSuccess": {
    "rejectedSpans": 2,
    "errorMessage": "2 spans dropped: trace id is not 16 bytes"
  }
}
```

**Errors:**

- `400` `invalid_body`: The body is not a valid `ExportTraceServiceRequest`.
- `401` `unauthorized`: The ingest key is missing, unknown or revoked.
- `413` `payload_too_large`: The body is larger than 4,000,000 bytes after decompression.
- `415` `unsupported_media_type`: The content type is neither `application/x-protobuf` nor `application/json`.
- `429` `rate_limited`: Too many requests. OTLP exporters honour `Retry-After` by themselves.
- `503` `unavailable`: Storage is not reachable. OTLP exporters retry `503` by themselves.

The errors every endpoint can answer (`401`, `403`, `429`, `500`, `503`) are on [Errors, limits, pagination](https://docs.sypnia.com/api/errors-limits-pagination).
