Instrumentar uma aplicação de servidor
Configure sua aplicação (Node.js, Python, Java, .NET, PHP, Go ou Ruby) com OpenTelemetry para que ela envie traces, métricas e logs ao APM do ARGUNIS.
Nesta página
Instrumentar é adicionar o OpenTelemetry à sua aplicação para que ela meça cada requisição e a envie ao ARGUNIS. Em quase todas as linguagens isso é feito sem mexer no código: você instala o pacote oficial, define algumas variáveis de ambiente e inicia a aplicação com o instrumentador.
Tudo de que você precisa está em Configurações → APM → Chave de API e SDK, seção SDK por linguagem e outras formas de enviar, aba Linguagens. Esta página explica os mesmos passos.
Antes de começar
O APM precisa estar ativo e você precisa ter um token de servidor. Veja Criar um token de ingestão.
Tenha à mão a URL de ingestão (OTLP/HTTP) que aparece no cartão Tokens de ingestão de Configurações → APM → Chave de API e SDK.
Se você criar o token na mesma tela, os blocos de código de Como instrumentar já vêm com sua URL de ingestão e seu token. Use Copiar em cada passo.
Os parâmetros que você obtém no Argunis Monitoring
Todas as linguagens usam as mesmas variáveis padrão do OpenTelemetry. Você as coloca no ambiente da sua aplicação (arquivo de serviço, contêiner, pool do IIS, configuração da nuvem):
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=otlpVariável | O que você coloca |
|---|---|
| O nome com que o serviço aparece em APM → Serviços |
| A URL de ingestão do cartão Status |
| Sempre |
|
|
| O ambiente ( |
|
|
Informar service.version a cada deploy serve para duas coisas: ver em qual versão um erro apareceu e fazer o ARGUNIS fechar sozinho os incidentes de erros quando uma nova versão não os tem mais. Se service.namespace coincidir com o nome de um grupo do inventário, o serviço fica nesse grupo.
Node.js
Instrumentação automática oficial (http, Express, Fastify, NestJS, pg, mysql, MongoDB, Redis, fetch, gRPC, Kafka e mais). CommonJS e ESM, Node 20.6 ou superior.
Instale os pacotes na aplicação:
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-nodeDefina as variáveis de ambiente acima e adicione
OTEL_NODE_RESOURCE_DETECTORS=allpara que ele detecte sozinho a nuvem, o contêiner e o servidor.Inicie com o registro do OpenTelemetry antes do seu código:
node --import @opentelemetry/auto-instrumentations-node/register dist/server.jsCom PM2 ou Docker, adicione a opção a NODE_OPTIONS:
NODE_OPTIONS="--import @opentelemetry/auto-instrumentations-node/register"Python
Django, Flask, FastAPI, Celery, requests, psycopg, SQLAlchemy, Redis e mais, com a distribuição oficial.
Instale a distribuição e as instrumentações do que o seu projeto usa:
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a installDefina as variáveis de ambiente e adicione
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=truepara enviar também os logs dologging.Inicie envolvendo o seu comando:
opentelemetry-instrument gunicorn app.wsgi:application --workers 4
# o: opentelemetry-instrument python app.pyJava e Kotlin
O agente oficial instrumenta Spring, Jakarta EE, Tomcat, JBoss/WildFly, WebSphere, JDBC (DB2, Oracle, SQL Server, PostgreSQL…), JMS, Kafka e mais. Java 8 ou superior.
Baixe o agente (em produção, fixe a versão):
curl -L -o /opt/otel/opentelemetry-javaagent.jar \
https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jarDefina as variáveis de ambiente.
Adicione o agente à JVM (no WebSphere ou no Tomcat, nos argumentos genéricos da JVM):
java -javaagent:/opt/otel/opentelemetry-javaagent.jar -jar app.jarNa AWS, no Azure ou no Google Cloud, ative o detector da nuvem correspondente:
-Dotel.resource.providers.aws.enabled=true
-Dotel.resource.providers.azure.enabled=true
-Dotel.resource.providers.gcp.enabled=true.NET
Instrumentação automática oficial para .NET 8 ou superior e .NET Framework 4.6.2 ou superior (ASP.NET Core, ASP.NET no IIS, HttpClient, SQL Server, EF Core…).
No Linux ou em um contêiner:
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.dllNo Windows com 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-OpenTelemetryForIISDepois defina as variáveis de ambiente (no IIS, no pool de aplicativos).
PHP
Extensão oficial e instrumentação automática de Laravel, Symfony, Slim, WordPress, PDO, curl e Guzzle. PHP 8.0 ou superior.
Instale a extensão e os pacotes (exemplo com 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-adapterDefina as variáveis de ambiente e adicione
OTEL_PHP_AUTOLOAD_ENABLED=true. No PHP-FPM, elas vão no pool comenv[...].
Go
SDK oficial com instrumentação de net/http, gRPC e database/sql. Em Go, sim, adicionam-se algumas linhas na inicialização.
Adicione os pacotes:
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/otelhttpAo iniciar a aplicação (o exportador lê as variáveis
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"))Defina as variáveis de ambiente.
Ruby
Rails, Sinatra, Sidekiq, ActiveRecord, Net::HTTP, Redis e mais.
Adicione as gems:
bundle add opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-allCrie
config/initializers/opentelemetry.rb:
require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure { |c| c.use_all }Defina as variáveis de ambiente.
Todos os SDKs enviam por OTLP/HTTP com protobuf para a URL de ingestão. Se um sistema só fala gRPC ou não sai para a internet, use o OpenTelemetry Collector como ponte. Veja Instrumentar em nuvens e contêineres.
O que acontece depois
Reinicie a aplicação e gere um pouco de tráfego. Em um ou dois minutos o serviço aparece em APM → Serviços com o nome que você colocou em OTEL_SERVICE_NAME. Se ele não aparecer, confira em APM → Configuração e ajustes o indicador Rejeitados hoje, e em Configurações → APM → Chave de API e SDK o Último uso do token.