Registry / observability / newrelic-telemetry-sdk

newrelic-telemetry-sdk

JSON →
library0.9.0pypypi✓ verified 22d ago

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.

pip install newrelic-telemetry-sdk
INSTALL
IMPORT
SIG · NEWRELIC-TELEMETRY
N
newrelic-telemetry-sdk
observabilitypythonv0.9.0
Install
1.7s avg
Import
243ms
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.250s · 18.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.7s · import 0.236s · 19MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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
from newrelic.agent import NewRelicContextFormatter
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.

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}")
Debug
Known issues
breakingSupport 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.
affects: >=0.9.0
breakingPython 2 support was removed in v0.6.0. Users on Python 2 must upgrade to Python 3.
fix
Upgrade Python to 3.x.
affects: >=0.6.0
breakingPrior 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.
affects: >=0.4.0
gotchaThe `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.
affects: >=0.5.0
gotchaIn 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.
affects: >=0.7.0
gotchaThe `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.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'newrelic_telemetry_sdk'
The `newrelic-telemetry-sdk` Python package is not installed in the environment where the code is being run.
fix
Install the library using pip: `pip install newrelic-telemetry-sdk`
HTTPError: 401 Client Error: Unauthorized for url: https://metric-api.newrelic.com/metric/v1
The New Relic license key provided to the SDK client is either missing, incorrect, or does not have the necessary permissions for data ingest. The SDK's internal `raise_for_status()` method converts API errors into Python exceptions. [5, 13]
fix
Ensure a valid New Relic Ingest License Key is supplied to the client. This is typically done by setting the `NEW_RELIC_LICENSE_KEY` environment variable or passing it directly to the client constructor.
HTTPError: 403 Client Error: Forbidden for url: https://metric-api.newrelic.com/metric/v1
Similar to a 401, this usually indicates that the provided New Relic license key is either invalid or lacks the necessary permissions to send data to the specified API endpoint. [5, 10]
fix
Verify that the New Relic license key is correct and that it has the 'Ingest - License' key type, which grants permission to send data to the Metric, Event, Log, and Trace APIs. [16]
requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))
This error, or similar `urllib3.exceptions.MaxRetryError` combined with messages like 'Client.Timeout exceeded', indicates a network connectivity issue preventing the SDK from reaching the New Relic ingest endpoint. This could be due to firewall restrictions, proxy issues, DNS problems, or transient New Relic service unavailability. [5, 17]
fix
Check network connectivity from the host running the SDK to New Relic's ingest endpoints (e.g., `metric-api.newrelic.com`). Verify firewall rules, proxy settings, and DNS resolution. If overriding the default host, ensure the correct endpoint is specified. Consider enabling debug logging for more detailed network insights.
Upgrade
Version history
0.9.0latest on PyPI · released Oct 23, 2025
Audit
Dependencies
urllib3requiredUsed for HTTP communication with New Relic APIs.
Agent activity
11 hits · last 30 days
node
8
OpenAI (training)
2
Resources