Elastic APM Agent

Overview

The Elastic APM agent runs inside your application process and captures transaction and span data as your code executes. It batches this data and forwards it to an APM server endpoint using the Elastic intake protocol (NDJSON over HTTP).

Kloudfuse exposes a compatible endpoint at:

https://<kloudfuse-hostname>/ingester/intake/v2/events

Redirecting the agent to this URL is the only configuration change required. No changes to your application code or instrumentation are needed.

Prerequisites

• An application already instrumented with an Elastic APM agent (Java, Node.js, Python, Ruby, Go, .NET, PHP, or RUM).
• The external hostname of your Kloudfuse cluster.
• If ingestion authentication is enabled, an API key — see Ingestion Authentication with API Key.

Configure the APM Agent

The Elastic APM agent reads its server URL from an environment variable or agent configuration file. Set ELASTIC_APM_SERVER_URL to the Kloudfuse ingester endpoint.

Environment Variable

Set the environment variable on the process running your application:

ELASTIC_APM_SERVER_URL=https://<kloudfuse-hostname>/ingester

If ingestion authentication is enabled, also set the secret token:

ELASTIC_APM_SERVER_URL=https://<kloudfuse-hostname>/ingester
ELASTIC_APM_SECRET_TOKEN=<token>

Kubernetes Deployment

Add the environment variables to your pod spec:

env:
  - name: ELASTIC_APM_SERVER_URL
    value: https://<kloudfuse-hostname>/ingester
  - name: ELASTIC_APM_SECRET_TOKEN    # omit if auth is not enabled
    valueFrom:
      secretKeyRef:
        name: kloudfuse-ingestion-credentials
        key: token
  - name: ELASTIC_APM_SERVICE_NAME
    value: <your-service-name>
  - name: ELASTIC_APM_ENVIRONMENT
    value: <environment>              # e.g. production, staging

Agent-Specific Configuration

Each Elastic APM agent also supports file-based configuration. The key and value are the same across all agents — only the config file format differs:

Refer to the Elastic APM agent documentation for your language for the full list of configuration options.

Verify Traces Are Arriving

After restarting your application with the updated configuration, generate some traffic (make HTTP requests, run transactions, etc.), then confirm traces are arriving in the Kloudfuse UI:

1. Click the APM tab, then select Services from the drop-down menu.
2. Set the time range to the last 15 minutes using the interval picker in the top-right corner.
3. Confirm that your service appears in the list. Services typically appear within a minute of the first trace arriving.
4. Click your service name to open the Service Detail view.
5. Select the Traces tab within the service detail to see individual trace records, latency distribution, and span breakdown.
6. To inspect a specific trace, click any row in the trace list to open the Trace Detail view, which shows the full span waterfall and associated metadata.

Troubleshooting

No Traces Appearing in Kloudfuse

If the APM Services page shows no data after generating traffic:

1. Check the agent logs. Most Elastic APM agents log connection errors at startup. Look for messages containing APM Server or intake:

   # Java example — check stderr/app logs for:
   # "Failed to connect to APM Server" or "APM server is not available"

2. Confirm the ELASTIC_APM_SERVER_URL value does not include a trailing path beyond "/ingester". The agent appends "/intake/v2/events" automatically — do not include it in the URL.
3. Verify the endpoint is reachable from your application host or pod:

   curl -sf https://<kloudfuse-hostname>/health/ && echo "reachable"

404 Errors for /ingester/config/v1/agents at Startup

At startup, Elastic APM agents attempt to fetch remote configuration from /ingester/config/v1/agents. Kloudfuse does not implement this endpoint — the 404 response is expected and harmless. The agent falls back to local configuration and continues delivering traces normally.

503 Errors on Trace Delivery

If the agent logs show HTTP 503 responses when submitting events:

• Confirm the request body is gzip-compressed. Elastic APM agents compress payloads by default — if compression is disabled (e.g., via ELASTIC_APM_DISABLE_SEND=true or custom transport configuration), the Kloudfuse ingester may return 503.
• Verify the Content-Type is application/x-ndjson and Content-Encoding is gzip. A plain-text NDJSON payload without compression will be rejected.

401 or 403 Errors

If the agent logs show 401 Unauthorized or 403 Forbidden responses from the intake endpoint:

• Ingestion authentication is enabled on your cluster.
• Set ELASTIC_APM_SECRET_TOKEN=<token> alongside ELASTIC_APM_SERVER_URL.
• Confirm the token is valid in Admin > Settings > Auth key labels in the Kloudfuse UI.

TLS Certificate Errors

If the agent cannot verify the Kloudfuse TLS certificate:

• Ensure the certificate is issued by a trusted CA — most agents validate TLS by default.
• If using a private CA, configure the agent to trust it via ELASTIC_APM_SERVER_CA_CERT_FILE (path to the CA bundle).
• For development only, disable verification with ELASTIC_APM_VERIFY_SERVER_CERT=false — do not use this in production.

External References

• Elastic APM Agents — Overview
• Elastic APM Java Agent — Configuration
• Elastic APM Node.js Agent — Configuration
• Elastic APM Python Agent — Configuration
• Elastic APM Intake API Reference