Elastic APM Agent

Kloudfuse accepts distributed trace data from applications instrumented with the Elastic APM agent. The agent sends traces to any server that implements the Elastic APM intake API — point it at the Kloudfuse ingester and traces appear alongside your metrics and logs without changing your instrumentation code.

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.

What Kloudfuse ingests

  • Transactions and spans are stored as spans.

  • Errors are stored as span errors.

  • Transactions the agent did not sample (transaction.sampled: false) are dropped.

  • Metric sets and other event types are ignored. To collect application metrics, use another source such as the OpenTelemetry Collector.

The endpoint accepts trace events only. Elastic RUM agent data, which uses a separate intake path, is not accepted.

Prerequisites

  • An application already instrumented with an Elastic APM agent (Java, Node.js, Python, Ruby, Go, .NET, or PHP).

  • The external hostname of your Kloudfuse cluster.

The Elastic intake endpoint does not support ingestion authentication. If ingestion authentication is enabled on your cluster, the ingester rejects Elastic APM requests with 403 Forbidden; see 403 Errors.

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

Kubernetes Deployment

Add the environment variables to your pod spec:

env:
  - name: ELASTIC_APM_SERVER_URL
    value: https://<kloudfuse-hostname>/ingester
  - name: ELASTIC_APM_SERVICE_NAME
    value: <your-service-name>
  - name: ELASTIC_APM_ENVIRONMENT
    value: <environment>              # e.g. production, staging
yaml

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:

Agent Config file Setting

Java

elasticapm.properties

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

Node.js

elastic-apm-node options object

serverUrl: 'https://<kloudfuse-hostname>/ingester'

Python

elastic-apm Django/Flask config

SERVER_URL: 'https://<kloudfuse-hostname>/ingester'

Ruby

config/elastic_apm.yml

server_url: https://<kloudfuse-hostname>/ingester

Go

apm.DefaultTracer() options

ELASTIC_APM_SERVER_URL environment variable

.NET

appsettings.json

"ServerUrl": "https://<kloudfuse-hostname>/ingester"

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. This request sends no trace data; a 415 response means the intake endpoint is reachable, and 403 means ingestion authentication is blocking it:

    curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  -H 'Content-Type: text/plain' --data 'x' \
  https://<kloudfuse-hostname>/ingester/intake/v2/events

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.

400 or 415 Errors on Trace Delivery

If the agent logs show HTTP 400 or 415 responses when submitting events, the payload does not match the Elastic intake format. Elastic APM agents send the correct format by default; these errors usually come from a proxy or custom transport that changes the request:

  • 415 Unsupported Media Type: the Content-Type must be application/x-ndjson.

  • 400 Bad Request: the first line of the payload must be a metadata event, every line must be valid JSON, and the Content-Encoding must be gzip, deflate, zstd, or absent (uncompressed).

403 Errors

If the agent logs show 403 Forbidden responses from the intake endpoint, ingestion authentication is enabled on your cluster. The Elastic intake endpoint does not accept an ingestion API key, and setting ELASTIC_APM_SECRET_TOKEN or ELASTIC_APM_API_KEY does not help. To send Elastic APM data, ingestion authentication must be disabled, or send traces with an OpenTelemetry SDK instead; see APM Instrumentation.

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