# OpenTelemetry

> Apunta a Sypnia un exportador de trazas OTLP/HTTP que ya tienes, con ejemplos para Python, Go, PHP, Rust, Java y el Collector, en qué se convierte cada span y qué se ignora exactamente al lanzar.

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/sdks/opentelemetry/

Esta página es para quien corre un backend que no es Node: Python, Go, PHP, Rust, Java, o cualquier otro con un SDK de OpenTelemetry. Sypnia acepta trazas en el protocolo de OpenTelemetry sobre HTTP (OTLP/HTTP), tanto en el motor de código abierto como en Sypnia Cloud. Los SDK propios de Sypnia para estos lenguajes están **\[Planeado]**; OpenTelemetry es la respuesta de hoy y seguirá teniendo soporte cuando existan.

**Al final tendrás:** las peticiones de tu backend en las trazas y en los números de rendimiento de Sypnia, sus excepciones como problemas, y sus spans unidos a la traza del navegador cuando la petición vino de una página que corre el [SDK del navegador](https://docs.sypnia.com/es/sdks/browser).

## Los ajustes, para cualquier lenguaje

No cambias código que ya funciona. Pon las variables de entorno estándar de OpenTelemetry:

**Sypnia Cloud**

`.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_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
OTEL_SERVICE_NAME=shop-api
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production,service.version=4f2a91c
```

**Alojamiento propio**

`.env`

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

| Variable                                      | Qué poner                                          | Por qué                                                                                                                  |
| --------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `OTEL_EXPORTER_OTLP_ENDPOINT`                 | Tu dirección de ingesta seguida de `/v1/otlp`.     | El exportador agrega `/v1/traces` por su cuenta, así que los spans van a `…/v1/otlp/v1/traces`.                          |
| `OTEL_EXPORTER_OTLP_HEADERS`                  | `Authorization=Bearer ` y tu llave de ingesta.     | La llave dice a qué proyecto pertenecen los spans. Es pública y solo puede enviar.                                       |
| `OTEL_EXPORTER_OTLP_PROTOCOL`                 | `http/protobuf`, o `http/json`.                    | Sypnia no acepta gRPC.                                                                                                   |
| `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` | `none`                                             | Sypnia solo recibe trazas. Sin esto, el exportador sigue intentando enviar métricas y logs y registra un `404` cada vez. |
| `OTEL_SERVICE_NAME`                           | Un nombre para este servicio.                      | Es el nombre que ves en sus spans.                                                                                       |
| `OTEL_RESOURCE_ATTRIBUTES`                    | `deployment.environment.name` y `service.version`. | El entorno (`production` por defecto) y la versión (release). Usa los mismos valores que tu frontend.                    |

Usa el mismo proyecto que tu frontend: una traza une partes de un mismo proyecto.

## Por lenguaje

Cada ejemplo supone que las variables de arriba están puestas. Los nombres de paquetes y comandos son los del proyecto OpenTelemetry; revisa su documentación para tu versión.

**Python**

```bash
pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http
opentelemetry-bootstrap -a install
opentelemetry-instrument python app.py
```

Python lee la variable de encabezados de forma estricta: escribe el espacio como `%20`.

`.env`

```bash
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
```

**Go**

Go no tiene agente: creas el exportador una vez, en `main`. Lee las variables de arriba.

`main.go`

```go
package main

import (
	"context"
	"log"
	"net/http"

	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
	"go.opentelemetry.io/otel/propagation"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
	ctx := context.Background()
	exporter, err := otlptracehttp.New(ctx)
	if err != nil {
		log.Fatal(err)
	}
	provider := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
	defer provider.Shutdown(ctx)
	otel.SetTracerProvider(provider)
	otel.SetTextMapPropagator(propagation.TraceContext{})

	mux := http.NewServeMux()
	mux.HandleFunc("POST /api/checkout", checkout)
	log.Fatal(http.ListenAndServe(":3000", otelhttp.NewHandler(mux, "shop-api")))
}
```

**PHP**

```bash
pecl install opentelemetry
composer require open-telemetry/sdk open-telemetry/exporter-otlp guzzlehttp/guzzle
```

`.env`

```bash
OTEL_PHP_AUTOLOAD_ENABLED=true
```

Luego agrega el paquete de instrumentación automática de tu framework, por ejemplo `open-telemetry/opentelemetry-auto-laravel` u `open-telemetry/opentelemetry-auto-symfony`.

**Rust**

`Cargo.toml`

```toml
[dependencies]
opentelemetry = "*"
opentelemetry_sdk = { version = "*", features = ["rt-tokio"] }
opentelemetry-otlp = { version = "*", default-features = false, features = ["trace", "http-proto", "reqwest-client"] }
```

Construye el exportador de spans OTLP con su transporte HTTP e instálalo en un proveedor de trazas con un procesador por lotes. El exportador lee las variables de arriba. El nombre del constructor cambió entre versiones de `opentelemetry-otlp`: sigue el ejemplo de la documentación del crate para la versión que fijes, y fija versiones reales en vez de `*`.

**Java**

Descarga `opentelemetry-javaagent.jar` del proyecto OpenTelemetry y arranca tu app con él:

```bash
java -javaagent:./opentelemetry-javaagent.jar -jar shop-api.jar
```

**Collector**

Si tus servicios ya envían a un OpenTelemetry Collector, agrega Sypnia como un exportador más del flujo de trazas:

`otel-collector.yaml`

```yaml
exporters:
  otlphttp/sypnia:
    endpoint: https://ingest.sypnia.com/v1/otlp
    headers:
      Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/sypnia]
```

## Comprueba que funciona

1. Arranca tu servicio y llama a una de sus rutas.
2. En menos de 10 minutos la ruta aparece en Rendimiento con una petición, y su traza está en Trazas.

Para probar la dirección y la llave sin tu app:

```bash
curl -i -X POST "https://ingest.sypnia.com/v1/otlp/v1/traces" \
  -H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans":[]}'
```

**Deberías ver:**`HTTP/2 200` y el cuerpo `{}`. Un `401` significa que la llave está mal; un `404`, que la ruta está mal.

## Unirse a la traza y a la sesión del navegador

**La traza se une sola.** El SDK del navegador envía el encabezado W3C `traceparent` con cada llamada a tu API, y los SDK de OpenTelemetry lo leen por defecto. Los spans de tu servidor llevan entonces el id de traza del navegador. Si la API está en otro origen que la página, lístala en `traceTargets` del SDK del navegador y permite el encabezado en CORS: mira [Navegador](https://docs.sypnia.com/es/sdks/browser).

**La sesión necesita un atributo.** El SDK del navegador también envía el id de la sesión en el encabezado `x-sypnia-session`. Cópialo al atributo `session.id` del span del servidor, y la petición aparece en la línea de tiempo de esa sesión:

`app.py`

```python
from flask import Flask, request
from opentelemetry import trace

app = Flask(__name__)

@app.before_request
def link_sypnia_session():
    session_id = request.headers.get("x-sypnia-session")
    if session_id:
        trace.get_current_span().set_attribute("session.id", session_id)
```

Sin él, la traza igual queda unida a la llamada del navegador, y por esa llamada a la sesión; el atributo importa para peticiones cuyo evento del navegador se perdió.

## En qué se convierte un span

| En OpenTelemetry                                                             | En Sypnia                                                                       |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Id de traza                                                                  | El id de la traza.                                                              |
| Recurso `service.name`                                                       | El servicio del span.                                                           |
| Recurso `deployment.environment.name`, o el antiguo `deployment.environment` | El entorno. `production` si falta.                                              |
| Recurso `service.version`                                                    | La versión (release).                                                           |
| Un span de clase `SERVER` con `http.route`                                   | Una petición en Rendimiento, y la raíz de la parte de ese servicio en la traza. |
| Un span de clase `CLIENT` con `db.system.name`                               | Una llamada a la base de datos.                                                 |
| Un span de clase `CLIENT` con `http.request.method`                          | Una llamada a otro servicio.                                                    |
| Cualquier otro span                                                          | Un paso interno, que se ve en la traza.                                         |
| Estado `ERROR` del span, o un evento de span `exception`                     | Un fallo. Una excepción con pila se vuelve un problema del lado del servidor.   |
| Atributo `session.id` del span (32 caracteres hex)                           | Une la traza con una sesión.                                                    |

## Lo que Sypnia no usa, al lanzar

| Lo envía OpenTelemetry                                                                   | Qué pasa                                                                                                                                                                |
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Métricas y logs (`/v1/metrics`, `/v1/logs`)                                              | No se aceptan: `404`. Los logs y las métricas propias están **\[Planeado]**.                                                                                            |
| Transporte gRPC                                                                          | No se acepta. Usa `http/protobuf` o `http/json`.                                                                                                                        |
| Eventos de span distintos de `exception`                                                 | Se descartan.                                                                                                                                                           |
| Enlaces entre spans                                                                      | Se descartan.                                                                                                                                                           |
| `tracestate` y baggage                                                                   | Ni se leen ni se guardan.                                                                                                                                               |
| Atributos cuyo nombre contiene `authorization`, `cookie`, `password`, `secret` o `token` | Se descartan en la ingesta.                                                                                                                                             |
| Más de 64 atributos en un span, o un valor de más de 256 caracteres                      | Los atributos de más se descartan; los valores largos se cortan.                                                                                                        |
| Más de 500 spans en una traza                                                            | Se conservan los primeros 500; el resto se cuenta.                                                                                                                      |
| La decisión de muestreo en `traceparent`                                                 | No se usa: Sypnia guarda lo que envías. Muestrea en tu SDK o en el Collector si envías demasiado.                                                                       |
| Nombres y correos de personas                                                            | OpenTelemetry no lleva ninguno que Sypnia lea. Una traza toma su persona de su sesión. Mira [Identificar personas](https://docs.sypnia.com/es/sdks/identifying-people). |

Los límites de una petición están en la [referencia de la API](https://docs.sypnia.com/es/api/otlp): un cuerpo de 4.000.000 de bytes tras descomprimir y 2.000 spans. Los exportadores por lotes estándar quedan muy por debajo de ambos.

## Lo que no obtienes por esta vía

OpenTelemetry envía trazas. Las sesiones, las grabaciones, los clics y el rendimiento de páginas vienen del [SDK del navegador](https://docs.sypnia.com/es/sdks/browser), que funciona con cualquier backend. En Sypnia Cloud, una traza cuenta como un evento, tenga los spans que tenga.

## Sigue con
