Our Trace API is used to send distributed tracing data to New Relic: either in our own generic format or the Zipkin data format. This API is also how trace data from some of our integrations and exporters is reported to New Relic.
Want to try out the Trace API? Make sure you've created a free New Relic account. No credit card required.
To skip some introductory content and get started quickly, go to Start reporting data.
What is the Trace API?
The Trace API is one way that New Relic collects distributed tracing data. We have some tracing tools that report data via this API (Infinite Tracing, our open source integrations, and our Telemetry SDKs), or you can use the API directly to create your own tracing implementation.
Reasons to use the Trace API:
- You have your own custom distributed tracing tool and want to see that data in New Relic without changing your instrumentation.
- You have a tool that emits tracing data but that requires a backend for trace storage.
- You want to report distributed tracing data to New Relic without the use of our installed solutions.
- You use Zipkin and want to see that trace data in New Relic without changing your instrumentation.
Want to understand how trace data relates to other New Relic data? Read about our data types.
Requirements
For details about what data you can send and how it is handled, see Rules and limits.
Sampling considerations
When using the Trace API, you have the option to enable Infinite Tracing. Whether you use Infinite Tracing has implications for how you configure sampling:
- Use your own sampling (no Infinite Tracing): If you don't use Infinite Tracing, it's assumed you want to use your own sampling implementation to sample traces before they're sent to us. (If your trace data exceeds our data limits, we do enact sampling.)
- Use Infinite Tracing: If you want to use Infinite Tracing, a typical approach is to send us 100% of your trace data and rely on Infinite Tracing sampling. (When you go through the Start reporting data instructions, below, you'll have an option for enabling Infinite Tracing.)
Start reporting data
The Trace API accepts trace data in these two JSON formats:
zipkin: the Zipkin JSON v2 trace data format (learn what Zipkin is). Get started sending Zipkin data.newrelic: our general format. If you don't have Zipkin-format data, use this. Get started sending New Relic-format data.
Having problems getting data to report? See Troubleshooting.
Find data
You can find data sent via the Trace API, or from integrations that use this API, in these locations:
- In our distributed tracing UI.
- By querying: For details about how to query and create custom charts, see Query distributed tracing data.
Next steps
Here are some additional steps to consider:
- Learn more about how distributed tracing works and the data structure.
- Decorate span data with custom attributes.
- Use our GraphQL-based NerdGraph API to programmatically query your trace data.