DocumentaciónAyuda

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=otlp

Variable

Qué pones

OTEL_SERVICE_NAME

El nombre con que el servicio aparece en APM → Servicios

OTEL_EXPORTER_OTLP_ENDPOINT

La URL de ingesta de la tarjeta Estado

OTEL_EXPORTER_OTLP_PROTOCOL

Siempre http/protobuf

OTEL_EXPORTER_OTLP_HEADERS

Authorization=Bearer%20 seguido de tu token de servidor (%20 es el espacio)

OTEL_RESOURCE_ATTRIBUTES

El ambiente (deployment.environment.name), el sistema al que pertenece (service.namespace) y la versión (service.version)

OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER

otlp, para enviar trazas, métricas y logs

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.

  1. Instala los paquetes en la aplicación:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
  1. Define las variables de entorno de arriba y agrega OTEL_NODE_RESOURCE_DETECTORS=all para que detecte sola la nube, el contenedor y el servidor.

  2. Arranca con el registro de OpenTelemetry antes que tu código:

node --import @opentelemetry/auto-instrumentations-node/register dist/server.js

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

  1. Instala la distribución y las instrumentaciones de lo que usa tu proyecto:

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
  1. Define las variables de entorno y agrega OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true para enviar también los logs de logging.

  2. Arranca envolviendo tu comando:

opentelemetry-instrument gunicorn app.wsgi:application --workers 4
# o: opentelemetry-instrument python app.py

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

  1. 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.jar
  1. Define las variables de entorno.

  2. 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.jar
  1. En 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.dll

En 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-OpenTelemetryForIIS

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

  1. 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-adapter
  1. Define las variables de entorno y agrega OTEL_PHP_AUTOLOAD_ENABLED=true. En PHP-FPM van en el pool con env[...].

Go

SDK oficial con instrumentación de net/http, gRPC y database/sql. En Go sí se agregan unas líneas al arrancar.

  1. 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/otelhttp
  1. Al 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"))
  1. Define las variables de entorno.

Ruby

Rails, Sinatra, Sidekiq, ActiveRecord, Net::HTTP, Redis y más.

  1. Agrega las gemas:

bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-all
  1. Crea config/initializers/opentelemetry.rb:

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure { |c| c.use_all }
  1. 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.

Relacionado

Buscar en Argunis Monitoring

Escribe al menos 2 letras para buscar en Argunis Monitoring.

↑↓ moverse · Enter abrir · Esc cerrar