New Relic Telemetry SDK

0.9.0 · active · verified Sat Apr 11

The `newrelic-telemetry-sdk` is a Python library for sending metrics, events, logs, and spans/traces directly to New Relic using HTTP APIs, without requiring the full New Relic agent. It provides clients for each telemetry type and supports Python 3.9 and newer. The library is actively maintained with regular releases.

Warnings

breaking Support for Python versions 3.7 and 3.8 has been removed in v0.9.0. Users on these versions must upgrade Python or pin to an older SDK version.
Fix: Upgrade Python to 3.9 or newer.
breaking Python 2 support was removed in v0.6.0. Users on Python 2 must upgrade to Python 3.
Fix: Upgrade Python to 3.x.
breaking Prior to v0.4.0, several APIs for creating and recording metrics were different. `Metric.from_value` was removed, `CountMetric`/`SummaryMetric` required `interval_ms`, and `Harvester.record` was replaced by `Harvester.batch.record` or `Batch.record`. `MetricBatch.record` was also replaced by specific `record_gauge`/`record_count`/`record_summary` methods.
Fix: Consult the v0.4.0 release notes and documentation for the updated API signatures and usage patterns.
gotcha The `insert_key` keyword argument was renamed to `license_key` in v0.5.0. While `NEW_RELIC_INSERT_KEY` may still appear in some older examples (e.g., for OpenTelemetry exporters), the SDK's clients now primarily expect `NEW_RELIC_LICENSE_KEY` or the `license_key` parameter.
Fix: Use `license_key` in client constructors and prefer `NEW_RELIC_LICENSE_KEY` for environment variables.
gotcha In v0.7.0, a `ValueError` raised by `send_batch()` for certain `urllib3` response issues was changed to a more appropriate `TypeError`. This might affect error handling logic.
Fix: Update exception handling to catch `TypeError` where applicable for `send_batch()` responses.
gotcha The `NewRelicLogFormatter` from this SDK is for formatting log messages to be sent *via* the SDK or a log forwarder. It is distinct from `NewRelicContextFormatter` found in the full New Relic Python APM agent, which automatically enriches logs with trace context. The SDK's `Log` object takes a message and attributes, it does not process `logging.LogRecord` directly in the same way an agent formatter would.
Fix: Understand the distinction: `NewRelicLogFormatter` prepares logs for direct submission or forwarding, while `NewRelicContextFormatter` (from the APM agent) integrates with Python's logging module for automatic context enrichment.

Install

pip install newrelic-telemetry-sdk Install latest version

Imports

MetricClient

from newrelic_telemetry_sdk import MetricClient

GaugeMetric

from newrelic_telemetry_sdk import GaugeMetric

CountMetric

from newrelic_telemetry_sdk import CountMetric

SummaryMetric

from newrelic_telemetry_sdk import SummaryMetric

EventClient

from newrelic_telemetry_sdk import EventClient

Event

from newrelic_telemetry_sdk import Event

LogClient

from newrelic_telemetry_sdk import LogClient

Log
```
from newrelic_telemetry_sdk import Log
```

SpanClient

from newrelic_telemetry_sdk import SpanClient

Span
```
from newrelic_telemetry_sdk import Span
```
Harvester
```
from newrelic_telemetry_sdk import Harvester
```
Used for sending data at a fixed interval in the background.
NewRelicLogFormatter
```
from newrelic_telemetry_sdk import NewRelicLogFormatter
```
NewRelicLogFormatter is for formatting structured logs to be sent via the SDK or forwarded by an agent. NewRelicContextFormatter is part of the full New Relic Python APM agent for logs in context.

Quickstart

This quickstart demonstrates sending a batch of different metric types (Gauge, Count, Summary) to New Relic using the `MetricClient`. It requires a `NEW_RELIC_LICENSE_KEY` environment variable for authentication.

import os
import time
from newrelic_telemetry_sdk import GaugeMetric, CountMetric, SummaryMetric, MetricClient

# Ensure NEW_RELIC_LICENSE_KEY is set in your environment
# Example: export NEW_RELIC_LICENSE_KEY="YOUR_NEW_RELIC_LICENSE_KEY"
LICENSE_KEY = os.environ.get("NEW_RELIC_LICENSE_KEY", "")

if not LICENSE_KEY:
    print("Warning: NEW_RELIC_LICENSE_KEY environment variable not set. Metrics will not be sent.")
else:
    metric_client = MetricClient(LICENSE_KEY)

    # Example: GaugeMetric - a single value at a point in time
    temperature = GaugeMetric("room_temperature", 72.5, {"units": "Fahrenheit"})

    # Example: CountMetric - track occurrences over an interval
    errors_count = CountMetric(name="application_errors", value=3, interval_ms=5000)

    # Example: SummaryMetric - track count, min, max, sum over an interval
    response_times_summary = SummaryMetric(
        "http_response_time", count=10, min=50, max=200, sum=1200, interval_ms=5000
    )

    batch = [temperature, errors_count, response_times_summary]

    try:
        response = metric_client.send_batch(batch)
        response.raise_for_status()  # Raises HTTPError for bad responses (4xx or 5xx)
        print("Sent metrics successfully!")
    except Exception as e:
        print(f"Failed to send metrics: {e}")

view raw JSON →