{"id":3712,"library":"newrelic-telemetry-sdk","title":"New Relic Telemetry SDK","description":"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.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/newrelic/newrelic-telemetry-sdk-python","tags":["newrelic","telemetry","metrics","spans","logs","observability","apm"],"install":[{"cmd":"pip install newrelic-telemetry-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for HTTP communication with New Relic APIs.","package":"urllib3","optional":false}],"imports":[{"symbol":"MetricClient","correct":"from newrelic_telemetry_sdk import MetricClient"},{"symbol":"GaugeMetric","correct":"from newrelic_telemetry_sdk import GaugeMetric"},{"symbol":"CountMetric","correct":"from newrelic_telemetry_sdk import CountMetric"},{"symbol":"SummaryMetric","correct":"from newrelic_telemetry_sdk import SummaryMetric"},{"symbol":"EventClient","correct":"from newrelic_telemetry_sdk import EventClient"},{"symbol":"Event","correct":"from newrelic_telemetry_sdk import Event"},{"symbol":"LogClient","correct":"from newrelic_telemetry_sdk import LogClient"},{"symbol":"Log","correct":"from newrelic_telemetry_sdk import Log"},{"symbol":"SpanClient","correct":"from newrelic_telemetry_sdk import SpanClient"},{"symbol":"Span","correct":"from newrelic_telemetry_sdk import Span"},{"note":"Used for sending data at a fixed interval in the background.","symbol":"Harvester","correct":"from newrelic_telemetry_sdk import Harvester"},{"note":"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.","wrong":"from newrelic.agent import NewRelicContextFormatter","symbol":"NewRelicLogFormatter","correct":"from newrelic_telemetry_sdk import NewRelicLogFormatter"}],"quickstart":{"code":"import os\nimport time\nfrom newrelic_telemetry_sdk import GaugeMetric, CountMetric, SummaryMetric, MetricClient\n\n# Ensure NEW_RELIC_LICENSE_KEY is set in your environment\n# Example: export NEW_RELIC_LICENSE_KEY=\"YOUR_NEW_RELIC_LICENSE_KEY\"\nLICENSE_KEY = os.environ.get(\"NEW_RELIC_LICENSE_KEY\", \"\")\n\nif not LICENSE_KEY:\n    print(\"Warning: NEW_RELIC_LICENSE_KEY environment variable not set. Metrics will not be sent.\")\nelse:\n    metric_client = MetricClient(LICENSE_KEY)\n\n    # Example: GaugeMetric - a single value at a point in time\n    temperature = GaugeMetric(\"room_temperature\", 72.5, {\"units\": \"Fahrenheit\"})\n\n    # Example: CountMetric - track occurrences over an interval\n    errors_count = CountMetric(name=\"application_errors\", value=3, interval_ms=5000)\n\n    # Example: SummaryMetric - track count, min, max, sum over an interval\n    response_times_summary = SummaryMetric(\n        \"http_response_time\", count=10, min=50, max=200, sum=1200, interval_ms=5000\n    )\n\n    batch = [temperature, errors_count, response_times_summary]\n\n    try:\n        response = metric_client.send_batch(batch)\n        response.raise_for_status()  # Raises HTTPError for bad responses (4xx or 5xx)\n        print(\"Sent metrics successfully!\")\n    except Exception as e:\n        print(f\"Failed to send metrics: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.9 or newer.","message":"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.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Upgrade Python to 3.x.","message":"Python 2 support was removed in v0.6.0. Users on Python 2 must upgrade to Python 3.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Consult the v0.4.0 release notes and documentation for the updated API signatures and usage patterns.","message":"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.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Use `license_key` in client constructors and prefer `NEW_RELIC_LICENSE_KEY` for environment variables.","message":"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.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Update exception handling to catch `TypeError` where applicable for `send_batch()` responses.","message":"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.","severity":"gotcha","affected_versions":">=0.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}