New Relic Agent

Kloudfuse accepts span and trace data from applications instrumented with the New Relic agent or SDK. Redirecting the agent to the Kloudfuse ingester is the only configuration change required — no re-instrumentation needed.

Overview

The New Relic agent runs inside your application and captures transaction and span data as your code executes. It sends this data to a collector endpoint over HTTPS.

Kloudfuse exposes a compatible collector endpoint — set NEW_RELIC_HOST to your Kloudfuse hostname and the agent forwards traces directly to Kloudfuse.

Kloudfuse supports APM data (spans and traces) from New Relic agents and SDKs. Non-APM data payloads (infrastructure metrics, browser, mobile) are not supported. Disable those features in the agent to prevent errors in your agent logs.

Prerequisites

  • An application already instrumented with a New Relic agent or SDK (Go, Java, Node.js, Python, Ruby, PHP, or .NET).

  • The external hostname of your Kloudfuse cluster.

  • If ingestion authentication is enabled, an API key — see Ingestion Authentication with API Key.

Configure the Agent

Environment Variable

Set NEW_RELIC_HOST to your Kloudfuse hostname on the process running your application:

NEW_RELIC_HOST=<kloudfuse-hostname>

The agent connects over HTTPS by default. No port or path suffix is required.

If ingestion authentication is enabled, also set the license key to your Kloudfuse API key:

NEW_RELIC_HOST=<kloudfuse-hostname>
NEW_RELIC_LICENSE_KEY=<token>

This environment variable approach works for Python, JavaScript, Node.js, and Ruby without any additional changes.

Go

The Go SDK does not read environment variables automatically unless you explicitly call ConfigFromEnvironment(). Make the following change to your application initialisation:

app, err := newrelic.NewApplication(
    newrelic.ConfigFromEnvironment(),
    // ... other config options
)
go

With ConfigFromEnvironment() in place, NEW_RELIC_HOST is picked up automatically.

PHP

The PHP agent does not support the NEW_RELIC_HOST environment variable.

Instead, set newrelic.daemon.collector_host in your newrelic.ini file:

newrelic.daemon.collector_host = <kloudfuse-hostname>
ini

Restart PHP-FPM or your web server after making this change.

Kubernetes

Add the environment variables to your pod spec:

env:
  - name: NEW_RELIC_HOST
    value: <kloudfuse-hostname>
  - name: NEW_RELIC_LICENSE_KEY    # omit if auth is not enabled
    valueFrom:
      secretKeyRef:
        name: kloudfuse-ingestion-credentials
        key: token
  - name: NEW_RELIC_APP_NAME
    value: <your-service-name>
yaml

Verify Traces Are Arriving

After restarting your application with the updated configuration, generate some traffic, 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. If no data appears immediately, allow up to 90 seconds for the New Relic agent to complete its first harvest cycle before checking again.

  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 for connection errors. New Relic agents log collector errors at startup — look for messages referencing the collector host or NR_COLLECTOR:

    # Python example
NEW_RELIC_LOG_LEVEL=debug NEW_RELIC_HOST=<kloudfuse-hostname> python app.py

  2. Confirm NEW_RELIC_HOST is set correctly and does not include a protocol prefix (https://) or trailing slash — the agent constructs the full URL internally.

  3. Verify the endpoint is reachable from your application host or pod:

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

Go Agent Ignoring NEW_RELIC_HOST

If the Go SDK is not picking up the environment variable:

  • Confirm newrelic.ConfigFromEnvironment() is included in the NewApplication call — see Configure Go SDK.

  • Without this option, the Go SDK uses only programmatic configuration and ignores environment variables entirely.

PHP Agent Not Forwarding Traces

If the PHP agent is sending to New Relic instead of Kloudfuse:

  • The PHP agent ignores NEW_RELIC_HOST. Use newrelic.daemon.collector_host in newrelic.ini instead — see Configure PHP Agent.

  • Confirm the ini change is in the correct file (check php --ini to see which files are loaded).

  • Restart PHP-FPM or Apache after editing newrelic.ini.

TypeError in Agent Logs After Connecting

After successfully connecting, the New Relic agent polls the collector for remote commands via get_agent_commands. Kloudfuse returns a response in a slightly different format from New Relic HQ, which causes some agent versions to log:

TypeError: string indices must be integers, not 'str'

This error occurs in the agent’s command-parsing code and is non-fatal. Traces, metrics, and spans are delivered to Kloudfuse normally on every harvest cycle.

OTLP Host Warning at Startup

At startup, some New Relic agent versions log:

Unable to find corresponding OTLP host using default otlp.nr-data.net

This is harmless. Kloudfuse receives New Relic data via the collector protocol (/agent_listener/invoke_raw_method), not OTLP. No configuration change is needed.

Traces Not Appearing Immediately

The New Relic agent buffers data locally and sends it in batches on the harvest cycle (default: 60 seconds). Traces and metrics do not appear in Kloudfuse until after the first harvest completes. Wait at least 60–90 seconds after startup before concluding that data is not arriving.

401 or Connection Refused Errors

If agent logs show authentication or connection errors:

  • If ingestion authentication is enabled, set NEW_RELIC_LICENSE_KEY=<token> alongside NEW_RELIC_HOST.

  • Confirm the token is active in Admin > Settings > Auth key labels in the Kloudfuse UI.

  • Test connectivity directly:

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

External References