Instrumentar una aplicación de servidor
Configura tu aplicación (Node.js, Python, Java, .NET, PHP, Go o Ruby) con OpenTelemetry para que envíe trazas, métricas y logs al APM de ARGUNIS.
En esta página
Instrumentar es agregar OpenTelemetry a tu aplicación para que mida cada petición y la envíe a ARGUNIS. En casi todos los lenguajes se hace sin tocar el código: instalas el paquete oficial, defines unas variables de entorno y arrancas la aplicación con el instrumentador.
Todo lo que necesitas está en Configuración → APM → API key y SDK, sección SDK por lenguaje y otras formas de enviar, pestaña Lenguajes. Esta página explica los mismos pasos.
Antes de empezar
El APM debe estar activo y debes tener un token de servidor. Ver Crear un token de ingesta.
Ten a mano la URL de ingesta (OTLP/HTTP) que aparece en la tarjeta Tokens de ingesta de Configuración → APM → API key y SDK.
Si creas el token en la misma pantalla, los bloques de código de Cómo instrumentar ya vienen con tu URL de ingesta y tu token. Usa Copiar en cada paso.
Los parámetros que obtienes en Argunis Monitoring
Todos los lenguajes usan las mismas variables estándar de OpenTelemetry. Las pones en el ambiente de tu aplicación (archivo de servicio, contenedor, pool de IIS, configuración de la nube):
OTEL_SERVICE_NAME=mi-servicio
OTEL_EXPORTER_OTLP_ENDPOINT=https://URL_DE_INGESTA
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20jtk_TU_TOKEN_DE_SERVIDOR
OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=produccion,service.namespace=mi-sistema,service.version=1.0.0
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlpVariable | Qué pones |
|---|---|
| El nombre con que el servicio aparece en APM → Servicios |
| La URL de ingesta de la tarjeta Estado |
| Siempre |
|
|
| El ambiente ( |
|
|
Informar service.version en cada despliegue sirve para dos cosas: ver en qué versión apareció un error y que ARGUNIS cierre solo los incidentes de errores cuando una versión nueva ya no los tiene. Si service.namespace coincide con el nombre de un grupo del inventario, el servicio queda en ese grupo.
Node.js
Instrumentación automática oficial (http, Express, Fastify, NestJS, pg, mysql, MongoDB, Redis, fetch, gRPC, Kafka y más). CommonJS y ESM, Node 20.6 o superior.
Instala los paquetes en la aplicación:
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-nodeDefine las variables de entorno de arriba y agrega
OTEL_NODE_RESOURCE_DETECTORS=allpara que detecte sola la nube, el contenedor y el servidor.Arranca con el registro de OpenTelemetry antes que tu código:
node --import @opentelemetry/auto-instrumentations-node/register dist/server.jsCon PM2 o Docker, agrega la opción a NODE_OPTIONS:
NODE_OPTIONS="--import @opentelemetry/auto-instrumentations-node/register"Python
Django, Flask, FastAPI, Celery, requests, psycopg, SQLAlchemy, Redis y más, con la distribución oficial.
Instala la distribución y las instrumentaciones de lo que usa tu proyecto:
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a installDefine las variables de entorno y agrega
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=truepara enviar también los logs delogging.Arranca envolviendo tu comando:
opentelemetry-instrument gunicorn app.wsgi:application --workers 4
# o: opentelemetry-instrument python app.pyJava y Kotlin
El agente oficial instrumenta Spring, Jakarta EE, Tomcat, JBoss/WildFly, WebSphere, JDBC (DB2, Oracle, SQL Server, PostgreSQL…), JMS, Kafka y más. Java 8 o superior.
Descarga el agente (en producción, fija la versión):
curl -L -o /opt/otel/opentelemetry-javaagent.jar \
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jarDefine las variables de entorno.
Agrega el agente a la JVM (en WebSphere o Tomcat, en los argumentos genéricos de la JVM):
java -javaagent:/opt/otel/opentelemetry-javaagent.jar -jar app.jarEn AWS, Azure o Google Cloud activa el detector de la nube que corresponda:
-Dotel.resource.providers.aws.enabled=true
-Dotel.resource.providers.azure.enabled=true
-Dotel.resource.providers.gcp.enabled=true.NET
Instrumentación automática oficial para .NET 8 o superior y .NET Framework 4.6.2 o superior (ASP.NET Core, ASP.NET en IIS, HttpClient, SQL Server, EF Core…).
En Linux o en un contenedor:
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O
sh ./otel-dotnet-auto-install.sh
. $HOME/.otel-dotnet-auto/instrument.sh
dotnet MiApp.dllEn Windows con IIS (PowerShell como administrador):
$m = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $m -OutFile OpenTelemetry.DotNet.Auto.psm1
Import-Module .\OpenTelemetry.DotNet.Auto.psm1
Install-OpenTelemetryCore
Register-OpenTelemetryForIISLuego define las variables de entorno (en IIS, en el pool de aplicaciones).
PHP
Extensión oficial y auto-instrumentación de Laravel, Symfony, Slim, WordPress, PDO, curl y Guzzle. PHP 8.0 o superior.
Instala la extensión y los paquetes (ejemplo con Laravel):
pecl install opentelemetry
echo "extension=opentelemetry.so" >> $(php --ini | grep "Loaded Configuration" | sed -e "s|.*:\s*||")
composer require open-telemetry/sdk open-telemetry/exporter-otlp \
open-telemetry/opentelemetry-auto-laravel open-telemetry/opentelemetry-auto-pdo php-http/guzzle7-adapterDefine las variables de entorno y agrega
OTEL_PHP_AUTOLOAD_ENABLED=true. En PHP-FPM van en el pool conenv[...].
Go
SDK oficial con instrumentación de net/http, gRPC y database/sql. En Go sí se agregan unas líneas al arrancar.
Agrega los paquetes:
go get go.opentelemetry.io/otel go.opentelemetry.io/otel/sdk \
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp \
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttpAl arrancar la aplicación (el exportador lee las variables
OTEL_*):
exp, err := otlptracehttp.New(ctx)
if err != nil { log.Fatal(err) }
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exp), sdktrace.WithResource(resource.Default()))
defer tp.Shutdown(ctx)
otel.SetTracerProvider(tp)
otel.SetTextMapPropagator(propagation.TraceContext{})
http.ListenAndServe(":8080", otelhttp.NewHandler(mux, "servidor"))Define las variables de entorno.
Ruby
Rails, Sinatra, Sidekiq, ActiveRecord, Net::HTTP, Redis y más.
Agrega las gemas:
bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-allCrea
config/initializers/opentelemetry.rb:
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure { |c| c.use_all }Define las variables de entorno.
Todos los SDK envían por OTLP/HTTP con protobuf a la URL de ingesta. Si un sistema solo habla gRPC o no sale a internet, usa el OpenTelemetry Collector como puente. Ver Instrumentar en nubes y contenedores.
Qué pasa después
Reinicia la aplicación y genera algo de tráfico. En uno o dos minutos el servicio aparece en APM → Servicios con el nombre que pusiste en OTEL_SERVICE_NAME. Si no aparece, revisa en APM → Configuración y ajustes el indicador Rechazados hoy, y en Configuración → APM → API key y SDK el Último uso del token.