# OTLP

> Envía trazas desde cualquier backend que hable OpenTelemetry, con el exportador estándar de OTLP/HTTP.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/api/otlp/

Para agentes: Referencia del endpoint OTLP/HTTP de trazas de Sypnia: variables del exportador, cómo se convierten los spans en datos de Sypnia, límites y errores.

Sypnia acepta trazas en el protocolo de OpenTelemetry por HTTP (OTLP/HTTP). Úsalo para cualquier backend que no tenga SDK de Sypnia. Solo trazas: los registros y las métricas de OTLP no se aceptan (los registros y las métricas propias están [planeados](https://docs.sypnia.com/es/reference/planned)).

## Configura un exportador

Define las variables estándar de OpenTelemetry. El exportador le agrega `/v1/traces` al endpoint por su cuenta.

`.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
```

En alojamiento propio, usa `<tu URL base>/v1/otlp` como endpoint.

## Cómo se convierten los spans en datos de Sypnia

| OpenTelemetry                                                                                                              | Sypnia                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| El id de traza                                                                                                             | El id de la traza. Una petición del navegador que llevaba el encabezado `traceparent` del SDK entra en la misma traza |
| `service.name` del recurso                                                                                                 | El `service` del span                                                                                                 |
| `deployment.environment.name` del recurso (o el anterior `deployment.environment`)                                         | El entorno. Por defecto `production`                                                                                  |
| `service.version` del recurso                                                                                              | La versión (release)                                                                                                  |
| Un span de servidor (`SPAN_KIND_SERVER`) con `http.route`                                                                  | Una llamada a la API en [Rendimiento](https://docs.sypnia.com/es/api/performance) y la raíz de la traza               |
| Un span de cliente con `db.system.name`                                                                                    | Una llamada a la base de datos (`kind: db`)                                                                           |
| Un span de cliente con `http.request.method`                                                                               | Una llamada HTTP saliente (`kind: http`)                                                                              |
| Estado `ERROR` del span, o un evento de span `exception`                                                                   | Una falla. Una excepción con pila se convierte en un problema del servidor                                            |
| El atributo `session.id` del span (32 hex), o el encabezado `x-sypnia-session` de la petición leído por tu instrumentación | Une la traza a una sesión                                                                                             |

De cada span se guardan hasta 64 atributos, con valores de hasta 256 caracteres. El motor descarta los atributos cuya clave contiene `authorization`, `cookie`, `password`, `secret` o `token`.

## Exportar trazas

`POST /v1/otlp/v1/traces` \[Motor, Nube]

El endpoint de trazas de OTLP/HTTP, tal como lo define la especificación de OpenTelemetry. El cuerpo es un `ExportTraceServiceRequest`, en protobuf (`application/x-protobuf`) o en JSON (`application/json`), con `Content-Encoding: gzip` si quieres. La respuesta es un `ExportTraceServiceResponse` en la misma codificación.

Cuando se rechazan algunos spans, la respuesta igual es `200` y `partialSuccess` dice cuántos y por qué, como exige el protocolo. Un exportador no debe reintentar un éxito parcial.

**Autenticación:** Llave de ingesta

**Límites**

- Cuerpo: 4.000.000 de bytes después de descomprimirlo.
- Spans por petición: 2.000. Spans por traza que se guardan: 500 (el resto se cuenta en `dropped_spans` de la traza).

**Petición:**

```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
```

**Cuerpo de la petición:**

```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
              }
            }
          ]
        }
      ]
    }
  ]
}
```

**Respuesta: Todos los spans guardados (200):**

```json
{}
```

**Respuesta: Algunos spans rechazados (200):**

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

**Errores:**

- `400` `invalid_body`: El cuerpo no es un `ExportTraceServiceRequest` válido.
- `401` `unauthorized`: Falta la llave de ingesta, es desconocida o está revocada.
- `413` `payload_too_large`: El cuerpo pesa más de 4.000.000 de bytes después de descomprimirlo.
- `415` `unsupported_media_type`: El tipo de contenido no es `application/x-protobuf` ni `application/json`.
- `429` `rate_limited`: Demasiadas peticiones. Los exportadores de OTLP respetan `Retry-After` por su cuenta.
- `503` `unavailable`: No se puede llegar al almacenamiento. Los exportadores de OTLP reintentan un `503` por su cuenta.

Los errores que cualquier endpoint puede responder (`401`, `403`, `429`, `500`, `503`) están en [Errores, límites, paginación](https://docs.sypnia.com/es/api/errors-limits-pagination).
