Application monitoring, from zero to useful traces

01 Start here #

APM is application tracing. The ZenPlus Agent already monitors the server—CPU, memory, disks, processes, services and Windows events. APM adds the application view: requests, errors, latency, dependencies and distributed traces.

How to read the examples in this guide

Configuration blocks are templates. Copy the relevant lines, then replace the values marked below before restarting the application.

02 How APM works #

Recommended: through the local Agent

User request
    ↓
IIS / Nginx / Apache
    ↓
Application runtime + OpenTelemetry
    ↓  OTLP/HTTP protobuf
127.0.0.1:4318  (ZenPlus Agent gateway)
    ↓  authenticated forwarding
ZenPlus appliance /v1/traces
    ↓
Overview → Services → Traces → Errors → Service Map

The gateway listens only on loopback by default, automatically manages its APM credential, buffers short interruptions, and forwards telemetry to the appliance.

Nginx, Apache and IIS are entry points—not the business application. Instrument the application runtime behind the web server: .NET, Java, Node.js, Python, PHP or another OpenTelemetry-supported runtime.

03 Read the APM Overview #

Open Applications → Overview. Start here during an incident. The selected time window in the upper-right controls every tile and chart.

04 Enable the ZenPlus Agent gateway #

Use the Agent gateway when the application and ZenPlus Agent run on the same server. This is the simplest and safest deployment.

Agent configuration example

Copy this into the Agent configuration only if the APM capability is not managed by policy. Change environment for the server. Keep both listen addresses on 127.0.0.1 when applications run on the same host.

apm:
  enabled: true
  environment: prod
  grpc_listen: 127.0.0.1:4317
  http_listen: 127.0.0.1:4318
  spool_max_bytes: 536870912
  max_request_bytes: 16777216

Verify on Windows

Get-Service ZenPlusAgent
Get-NetTCPConnection -State Listen -LocalPort 4317,4318 |
  Select-Object LocalAddress,LocalPort,OwningProcess

Verify on Linux

sudo systemctl status zenplus-agent --no-pager
sudo ss -lntp | grep -E '127\.0\.0\.1:(4317|4318)'

05 Configure IIS and .NET #

This method instruments ASP.NET on IIS without changing application source code. Run Windows PowerShell 5.1 as Administrator.

1. Find the correct Web.config

Web.config is normally in the physical root folder of the IIS site or application. Do not edit applicationHost.config, machine.config, or a different website’s file.

1. Open IIS Manager.
2. In Connections, expand the server and Sites.
3. Select the exact website or application you want to monitor. If the application is under Default Web Site, select the application—not only its parent website.
4. In the right Actions pane, select Basic Settings.
5. Read the Physical path. That folder is where you look for Web.config.

6. Close Basic Settings without changing it, then select Explore in the Actions pane.
7. In the opened folder, locate Web.config. Windows may display it as web.config; file-name capitalization does not matter.
8. Make a backup copy before editing. Open the file with an administrator text editor only when the folder permissions require it.

2. Confirm the application pool

3. Install OpenTelemetry .NET automatic instrumentation

# Windows PowerShell 5.1 — run as Administrator
$moduleUrl = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$modulePath = Join-Path $env:TEMP "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $moduleUrl -OutFile $modulePath -UseBasicParsing
Import-Module $modulePath
Install-OpenTelemetryCore

4. Add the OpenTelemetry values to Web.config

For ASP.NET Framework, merge the following <add> entries into the application’s existing <appSettings> section.

<!-- COPY these entries inside the existing <appSettings> section. -->
<add key="OTEL_SERVICE_NAME"
     value="REPLACE_WITH_SERVICE_NAME" />
<add key="OTEL_TRACES_EXPORTER" value="otlp" />
<add key="OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"
     value="http://127.0.0.1:4318/v1/traces" />
<add key="OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"
     value="http/protobuf" />
<add key="OTEL_METRICS_EXPORTER" value="none" />
<add key="OTEL_LOGS_EXPORTER" value="none" />
<add key="OTEL_RESOURCE_ATTRIBUTES"
     value="deployment.environment.name=REPLACE_WITH_ENVIRONMENT,service.version=REPLACE_WITH_VERSION" />

Exactly what must change

If <appSettings> does not exist

Create one inside the existing <configuration> element, then place the entries above inside it:

<configuration>
  <appSettings>
    <!-- Paste the OTEL <add> entries here. -->
  </appSettings>
  <!-- Keep all other existing sections here. -->
</configuration>

5. Register IIS and restart

Import-Module $modulePath
Register-OpenTelemetryForIIS

6. Generate traffic

Invoke-WebRequest https://your-app.example/health -UseBasicParsing

Replace https://your-app.example/health with a real dynamic URL from the application, then open APM → Traces after a few seconds. A separate IIS application pool per application is recommended; on .NET Framework, the first application loaded in a shared pool can determine the OpenTelemetry configuration for that worker process.

06 Nginx, Apache and other common stacks #

Keep the existing Nginx or Apache reverse-proxy configuration. Instrument the application process behind it and send traces to the local Agent gateway.

Python: Django, Flask or FastAPI behind Nginx/Apache

python -m pip install opentelemetry-distro opentelemetry-exporter-otlp-proto-http
opentelemetry-bootstrap -a install

export OTEL_SERVICE_NAME="customer-api"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://127.0.0.1:4318/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=prod,service.version=1.0.0"

opentelemetry-instrument gunicorn myproject.wsgi:application

Node.js: Express, NestJS or similar

npm install --save @opentelemetry/api @opentelemetry/auto-instrumentations-node

export OTEL_SERVICE_NAME="web-portal"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://127.0.0.1:4318/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"

node server.js

Java: Spring Boot, Tomcat or Jetty

sudo install -d /opt/opentelemetry
sudo curl -L \
  -o /opt/opentelemetry/opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

export OTEL_SERVICE_NAME="billing-service"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://127.0.0.1:4318/v1/traces"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"
export JAVA_TOOL_OPTIONS="-javaagent:/opt/opentelemetry/opentelemetry-javaagent.jar"

07 Direct-to-appliance mode #

Use direct mode only when an Agent cannot run on the application host.

1. Open Applications → Settings → Ingest keys.
2. Create an SDK key for the correct environment.
3. Copy it immediately; the plaintext key is shown once.
4. Set the appliance URL and authorization header in the application runtime.

export OTEL_SERVICE_NAME="orders-api"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://zenplus.example/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer zpi_REPLACE_WITH_KEY"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"

08 Verify and troubleshoot #

Successful result

1. Send several normal requests, one slow request and—only in a test environment—one controlled error.
2. Open Applications → Services and select a 15-minute or 1-hour window.
3. Confirm the service name, environment, throughput, error rate and latency.
4. Open Traces and select a request to inspect its waterfall.

If the screen is empty