Milestone 5 Complete: New Relic OTLP Integration for Heka Insights Agent

In this milestone, we focused on making New Relic integration first-class in the Heka Insights Agent, while still using the same OTLP HTTP exporter foundation.

Repository: https://github.com/ronin1770/heka-insights-agent

Milestone 5 Goal

Milestone 5 was about shipping a reliable, low-friction New Relic path without creating a separate proprietary exporter.

Scope covered:

• New Relic preset configuration layer
• Automatic New Relic auth header injection
• Endpoint and required field validation
• Documentation updates with practical examples
• Integration tests for preset behavior

What We Changed

1. New Relic preset mode (EXPORTER_TYPE=newrelic_otlp)

We added a preset resolver that maps New Relic-specific environment variables into OTLP HTTP exporter inputs.

Required variables:

• NEWRELIC_OTLP_ENDPOINT
• NEWRELIC_API_KEY
• NEWRELIC_SERVICE_NAME

Optional variables:

• NEWRELIC_ENVIRONMENT
• NEWRELIC_HOST_NAME

2. Automatic auth header injection

When EXPORTER_TYPE=newrelic_otlp is selected, the runtime now injects:

• api-key: <NEWRELIC_API_KEY>

No manual OTLP_HTTP_HEADERS setup is required for baseline New Relic auth.

3. Precedence behavior

In preset mode, NEWRELIC_* values take precedence over conflicting generic OTLP_* values.

Examples:

• NEWRELIC_API_KEY overrides any conflicting OTLP_HTTP_HEADERS api-key
• NEWRELIC_SERVICE_NAME overrides service.name from OTLP_RESOURCE_ATTRIBUTES

4. Validation hardening

We now fail fast on invalid or missing required New Relic settings:

• missing required keys -> startup error
• invalid endpoint format -> startup error (must be absolute http:// or https://)

5. Documentation updates

We updated project docs and examples to include New Relic preset usage and expected test flows.

Commands to Run Tests

Unit tests for config behavior

PYTHONPATH=src python3 -m unittest -v tests.test_config_otlp_env

New Relic Docker integration tests (explicit)

docker compose -f docker-compose.test.yml run --rm \
  -e RUN_OTLP_INTEGRATION=1 \
  -e OTLP_IT_HOST=host.docker.internal \
  test-runner \
  pytest -vv -s -rs tests/milestone-5/test_newrelic_otlp_integration.py

Expected summary:

collected 3 items
...
3 passed

Full OTLP/HTTP Docker test stack

docker compose -f docker-compose.test.yml up --build --abort-on-container-exit --exit-code-from test-runner

Why This Matters

With Milestone 5 complete, teams can onboard New Relic using a predictable preset path:

• less config ambiguity
• safer startup behavior through validation
• standardized OTLP transport path
• stronger confidence through Docker-backed integration tests

Next steps will continue building on this exporter foundation while keeping the runtime predictable and vendor-friendly.