DocumentaciónHelp

Instrument a server application

Set up your application (Node.js, Python, Java, .NET, PHP, Go or Ruby) with OpenTelemetry so it sends traces, metrics and logs to ARGUNIS APM.

On this page

Instrumenting means adding OpenTelemetry to your application so it measures each request and sends it to ARGUNIS. In almost every language this is done without touching the code: you install the official package, define a few environment variables, and start the application with the instrumenter.

Everything you need is in Settings → APM → API key and SDK, section SDK by language and other ways to send, Languages tab. This page explains the same steps.

Before you start

  • APM must be active and you must have a server token. See Create an ingest token.

  • Have the Ingest URL (OTLP/HTTP) at hand; it appears on the Ingest tokens card in Settings → APM → API key and SDK.

If you create the token on the same screen, the How to instrument code blocks already come with your ingest URL and your token. Use Copy on each step.

The parameters you get in Argunis Monitoring

All languages use the same standard OpenTelemetry variables. You set them in your application's environment (service file, container, IIS pool, cloud configuration):

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

What to set

OTEL_SERVICE_NAME

The name the service shows in APM → Services

OTEL_EXPORTER_OTLP_ENDPOINT

The Ingest URL from the Status card

OTEL_EXPORTER_OTLP_PROTOCOL

Always http/protobuf

OTEL_EXPORTER_OTLP_HEADERS

Authorization=Bearer%20 followed by your server token (%20 is the space)

OTEL_RESOURCE_ATTRIBUTES

The environment (deployment.environment.name), the system it belongs to (service.namespace) and the version (service.version)

OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER

otlp, to send traces, metrics and logs

Reporting service.version on each deployment serves two purposes: seeing which version an error appeared in, and letting ARGUNIS automatically close error incidents when a new version no longer has them. If service.namespace matches the name of an inventory group, the service goes into that group.

Node.js

Official automatic instrumentation (http, Express, Fastify, NestJS, pg, mysql, MongoDB, Redis, fetch, gRPC, Kafka and more). CommonJS and ESM, Node 20.6 or later.

  1. Install the packages in the application:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
  1. Define the environment variables above and add OTEL_NODE_RESOURCE_DETECTORS=all so it detects the cloud, container and server on its own.

  2. Start with the OpenTelemetry registration before your code:

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

With PM2 or Docker, add the option to NODE_OPTIONS:

NODE_OPTIONS="--import @opentelemetry/auto-instrumentations-node/register"

Python

Django, Flask, FastAPI, Celery, requests, psycopg, SQLAlchemy, Redis and more, with the official distribution.

  1. Install the distribution and the instrumentations for what your project uses:

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
  1. Define the environment variables and add OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true to also send the logging logs.

  2. Start by wrapping your command:

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

Java and Kotlin

The official agent instruments Spring, Jakarta EE, Tomcat, JBoss/WildFly, WebSphere, JDBC (DB2, Oracle, SQL Server, PostgreSQL…), JMS, Kafka and more. Java 8 or later.

  1. Download the agent (in production, pin the version):

curl -L -o /opt/otel/opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
  1. Define the environment variables.

  2. Add the agent to the JVM (in WebSphere or Tomcat, in the generic JVM arguments):

java -javaagent:/opt/otel/opentelemetry-javaagent.jar -jar app.jar
  1. On AWS, Azure or Google Cloud, enable the matching cloud detector:

-Dotel.resource.providers.aws.enabled=true
-Dotel.resource.providers.azure.enabled=true
-Dotel.resource.providers.gcp.enabled=true

.NET

Official automatic instrumentation for .NET 8 or later and .NET Framework 4.6.2 or later (ASP.NET Core, ASP.NET on IIS, HttpClient, SQL Server, EF Core…).

On Linux or in a container:

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

On Windows with IIS (PowerShell as administrator):

$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

Then define the environment variables (on IIS, in the application pool).

PHP

Official extension and auto-instrumentation for Laravel, Symfony, Slim, WordPress, PDO, curl and Guzzle. PHP 8.0 or later.

  1. Install the extension and the packages (Laravel example):

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 the environment variables and add OTEL_PHP_AUTOLOAD_ENABLED=true. In PHP-FPM they go in the pool with env[...].

Go

Official SDK with instrumentation for net/http, gRPC and database/sql. In Go you do add a few lines at startup.

  1. Add the packages:

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. When the application starts (the exporter reads the OTEL_* variables):

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 the environment variables.

Ruby

Rails, Sinatra, Sidekiq, ActiveRecord, Net::HTTP, Redis and more.

  1. Add the gems:

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

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure { |c| c.use_all }
  1. Define the environment variables.

All SDKs send over OTLP/HTTP with protobuf to the ingest URL. If a system only speaks gRPC or has no internet access, use the OpenTelemetry Collector as a bridge. See Instrument in clouds and containers.

What happens next

Restart the application and generate some traffic. Within a minute or two the service appears in APM → Services with the name you set in OTEL_SERVICE_NAME. If it doesn't appear, check the Rejected today indicator in APM → Configuration and settings, and the token's Last used in Settings → APM → API key and SDK.

Related

Search Argunis Monitoring

Type at least 2 characters to search Argunis Monitoring.

↑↓ to navigate · Enter to open · Esc to close