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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.250s · 18.9MB
glibcpy 3.10–3.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}")
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.
fixInstall 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]
fixEnsure 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]
fixVerify 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]
fixCheck 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.