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.
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.
Los ajustes, para cualquier lenguaje
No cambias código que ya funciona. Pon las variables de entorno estándar de OpenTelemetry:
Sypnia Cloud
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=4f2a91cAlojamiento propio
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
pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http
opentelemetry-bootstrap -a install
opentelemetry-instrument python app.pyPython lee la variable de encabezados de forma estricta: escribe el espacio como %20.
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2eGo
Go no tiene agente: creas el exportador una vez, en main. Lee las variables de arriba.
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
pecl install opentelemetry
composer require open-telemetry/sdk open-telemetry/exporter-otlp guzzlehttp/guzzleOTEL_PHP_AUTOLOAD_ENABLED=trueLuego 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
[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:
java -javaagent:./opentelemetry-javaagent.jar -jar shop-api.jarCollector
Si tus servicios ya envían a un OpenTelemetry Collector, agrega Sypnia como un exportador más del flujo de trazas:
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
- Arranca tu servicio y llama a una de sus rutas.
- 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:
curl -i -X POST "https://ingest.sypnia.com/v1/otlp/v1/traces" \
-H "Authorization: Bearer spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e" \
-H "Content-Type: application/json" \
-d '{"resourceSpans":[]}'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.
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:
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. |
Los límites de una petición están en la referencia de la API: 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, que funciona con cualquier backend. En Sypnia Cloud, una traza cuenta como un evento, tenga los spans que tenga.
Sigue con
- Cómo se une una traza, y cuándo falló un span.
-
OTLP en la referencia de la API
El endpoint, sus respuestas y sus límites. - SDK nativos para otros lenguajes, logs y métricas.