Docs

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 MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Los ajustes, para cualquier lenguaje
  2. Por lenguaje
  3. Comprueba que funciona
  4. Unirse a la traza y a la sesión del navegador
  5. En qué se convierte un span
  6. Lo que Sypnia no usa, al lanzar
  7. Lo que no obtienes por esta vía
  8. Sigue con

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

.env
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
VariableQué ponerPor qué
OTEL_EXPORTER_OTLP_ENDPOINTTu 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_HEADERSAuthorization=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_PROTOCOLhttp/protobuf, o http/json.Sypnia no acepta gRPC.
OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTERnoneSypnia solo recibe trazas. Sin esto, el exportador sigue intentando enviar métricas y logs y registra un 404 cada vez.
OTEL_SERVICE_NAMEUn nombre para este servicio.Es el nombre que ves en sus spans.
OTEL_RESOURCE_ATTRIBUTESdeployment.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

Terminal
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
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e

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:

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

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
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 OpenTelemetryEn Sypnia
Id de trazaEl id de la traza.
Recurso service.nameEl servicio del span.
Recurso deployment.environment.name, o el antiguo deployment.environmentEl entorno. production si falta.
Recurso service.versionLa versión (release).
Un span de clase SERVER con http.routeUna 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.nameUna llamada a la base de datos.
Un span de clase CLIENT con http.request.methodUna llamada a otro servicio.
Cualquier otro spanUn paso interno, que se ve en la traza.
Estado ERROR del span, o un evento de span exceptionUn 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 OpenTelemetryQué pasa
Métricas y logs (/v1/metrics, /v1/logs)No se aceptan: 404. Los logs y las métricas propias están Planeado.
Transporte gRPCNo se acepta. Usa http/protobuf o http/json.
Eventos de span distintos de exceptionSe descartan.
Enlaces entre spansSe descartan.
tracestate y baggageNi se leen ni se guardan.
Atributos cuyo nombre contiene authorization, cookie, password, secret o tokenSe descartan en la ingesta.
Más de 64 atributos en un span, o un valor de más de 256 caracteresLos atributos de más se descartan; los valores largos se cortan.
Más de 500 spans en una trazaSe conservan los primeros 500; el resto se cuenta.
La decisión de muestreo en traceparentNo se usa: Sypnia guarda lo que envías. Muestrea en tu SDK o en el Collector si envías demasiado.
Nombres y correos de personasOpenTelemetry 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

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar