Implement a Dimensional Metrics API

[kbford56]

Description

Today customers can only report timeslice metrics through our language agents. The feature ergonomics are lacking. These custom metrics are not dimensional, they are simple flat metric names that must be queried through the “magical” newrelic.timeslice.value metric, hindering discoverability.

Acceptance Criteria

We will add a new dimensional metric API to our language agents supporting count and summary metrics.  

Design Consideration/Limitations

Custom metric data will be more discoverable as a normal dimensional metric.  DM data is more  usable - customers can filter and facet on autocompletable attribute names. The API and data format is closer to modern telemetry apis like OTel.  Customers can build dashboards using these metrics, and if they later switch to OpenTelemetry agents, they will be able to report the same metrics into their existing dashboards.  A dimensional metric API is a compelling feature that may drive agent upgrades.

Dependencies

N/A

Additional context

Full document with details: APM Agent Dimensional metrics API - Google Docs

[workato-integration[bot]]

https://new-relic.atlassian.net/browse/NR-187787

[jasonjkeller]

We currently support sending dimensional metrics via OpenTelemetry APIs.

This is achieved via instrumenting the OTel SDK and auto-configuring it to send metrics to a specific APM entity (the same one associated with the APM Java agent): https://github.com/newrelic/newrelic-java-agent/tree/main/instrumentation/opentelemetry-sdk-extension-autoconfigure-1.28.0

Instructions on using this functionality are listed below.

---

New Relic Java Agent Configuration

To use the OpenTelemetry dimensional metric functionality incorporated into the New Relic Java agent you must enable the following config options:

Configuration via yaml:

opentelemetry:
  sdk: 
    autoconfigure:
      enabled: true

Configuration via system property:

-Dopentelemetry.sdk.autoconfigure.enabled=true

Configuration via environment variable:

NEW_RELIC_OPENTELEMETRY_SDK_AUTOCONFIGURE_ENABLED=true

OpenTelemetry Dimensional Metrics

OpenTelemetry APIs can be used to create dimensional metrics which will be detected by the New Relic Java agent and reported to the APM entity being monitored by the New Relic Java agent.

To use this functionality, enable the feature as documented above, add the required opentelemetry dependencies to your application:

    implementation(platform("io.opentelemetry:opentelemetry-bom:1.44.1"))
    implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure")
    implementation("io.opentelemetry:opentelemetry-exporter-otlp")

Then utilize the OpenTelemetry APIs to record dimensional metrics:

LongCounter longCounter = GlobalOpenTelemetry.get().getMeterProvider().get("my-application").counterBuilder("my.application.counter").build();
longCounter.add(1, Attributes.of(AttributeKey.stringKey("foo"), "bar"));

Any recorded dimensional metrics can be found in the Metrics Explorer for the associated APM entity and can be used to build custom dashboards.