--- title: Report traces via the Trace API (New Relic format) source: https://docs.newrelic.com/docs/distributed-tracing/trace-api/report-new-relic-format-traces-trace-api --- If you want to create your own tracing implementation, you can use our [Trace API](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/trace-api/introduction-trace-api). This doc explains how to send traces in our general format, also known as `newrelic` format. (To send Zipkin-format data, see [Zipkin](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/report-zipkin-format-traces-trace-api).) ## Get started [#send-data-overview] Using our Trace API is as simple as: - Sending trace data in the expected format (in this case, our `newrelic` format). - Sending that data to the appropriate [endpoint](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/trace-api/trace-api-general-requirements-limits#requirements). Before using the Trace API, you should decide whether you want to use Infinite Tracing. To learn more about this, see [Intro to Infinite Tracing](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/infinite-tracing/introduction-infinite-tracing) and [Sampling considerations](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/trace-api/introduction-trace-api#sampling). To get started using the Trace API, follow one of these paths: - Want to use [Infinite Tracing](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/trace-api/introduction-trace-api#sampling)? Follow the [Set up a trace observer](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/infinite-tracing/set-trace-observer#set-up) instructions. That walks you through creating a trace observer and sending a sample payload to the trace observer endpoint. - Don't want Infinite Tracing? See how to send a [sample payload](#new-relic-quick-start) (below). ## Send sample trace payload (non-Infinite Tracing) [#new-relic-quick-start] The following explains how to send a standard (non-[Infinite Tracing](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/trace-api/introduction-trace-api#sampling)) payload to the Trace API using our `newrelic` format. 1. Get a license key for the account you want to report data to. 2. Insert that key into the following JSON and then send the JSON to our endpoint. Note: if you have an EU or JP New Relic account, use the appropriate [regional endpoint](https://docs.newrelic.com/docs/distributed-tracing/trace-api/trace-api-general-requirements-limits#requirements) instead. ```bash curl -i -H 'Content-Type: application/json' \ -H 'Api-Key: YOUR_LICENSE_KEY' \ -H 'Data-Format: newrelic' \ -H 'Data-Format-Version: 1' \ -X POST \ -d '[ { "common": { "attributes": { "service.name": "Test Service A", "host": "host123.example.com" } }, "spans": [ { "trace.id": "123456", "id": "ABC", "attributes": { "duration.ms": 12.53, "name": "/home" } }, { "trace.id": "123456", "id": "DEF", "attributes": { "error.message": "Invalid credentials", "service.name": "Test Service A", "host": "host456.example.com", "duration.ms": 2.97, "name": "/auth", "parent.id": "ABC" } } ] } ]' 'https://trace-api.newrelic.com/trace/v1' ``` > #### 💡 TIP > > If you're sending more than one `POST`, change the `trace.id` to a unique value. Sending the same payload or span `id` multiple times for the same `trace.id` may result in fragmented traces in the UI. 3. If your test returned `HTTP/1.1 202 Accepted`, go to [our UI](https://one.newrelic.com/launcher/distributed-tracing-nerdlets.distributed-tracing?launcher=eyJ0aW1lUmFuZ2UiOnsiYmVnaW5fdGltZSI6bnVsbCwiZW5kX3RpbWUiOm51bGwsImR1cmF0aW9uIjoxODAwMDAwfSwiJGlzRmFsbGJhY2tUaW1lUmFuZ2UiOnRydWV9&pane=eyJuZXJkbGV0SWQiOiJkaXN0cmlidXRlZC10cmFjaW5nLW5lcmRsZXRzLmRpc3RyaWJ1dGVkLXRyYWNpbmctbGF1bmNoZXIiLCJzb3J0SW5kZXgiOjAsInNvcnREaXJlY3Rpb24iOiJERVNDIiwicXVlcnkiOnsib3BlcmF0b3IiOiJBTkQiLCJpbmRleFF1ZXJ5Ijp7ImNvbmRpdGlvblR5cGUiOiJJTkRFWCIsIm9wZXJhdG9yIjoiQU5EIiwiY29uZGl0aW9ucyI6W119LCJzcGFuUXVlcnkiOnsib3BlcmF0b3IiOiJBTkQiLCJjb25kaXRpb25TZXRzIjpbeyJjb25kaXRpb25UeXBlIjoiU1BBTiIsIm9wZXJhdG9yIjoiQU5EIiwiY29uZGl0aW9ucyI6W3siYXR0ciI6InNlcnZpY2UubmFtZSIsIm9wZXJhdG9yIjoiRVEiLCJ2YWx1ZSI6IlRlc3QgU2VydmljZSBBIn1dfV19fX0=) to see a query of your test data using the span attribute `service.name = Test Service A`. > #### 💡 TIP > > Traces may take up to one minute to be processed by both the trace observer and the Trace API. ## Trace API payload (New Relic format) [#new-relic-guidelines] The Trace API JSON payload is an array of objects, with each object representing a single trace. Each of these objects requires a `spans` key and may also include a `common` key. `spans` (required) contains an array of objects, with each object representing a span. `common` (optional) shares information across multiple spans. ### The Span object in the `spans` array | field | type | description | required | default | | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------- | | `id` | _string_ | Unique identifier for this span. | yes | N/A | | `trace.id` | _string_ | Unique identifier shared by all spans within a single trace. | yes | N/A | | `timestamp` | _long_ | Span start time in [milliseconds since the Unix epoch](https://currentmillis.com/). | no | Current time in UTC time zone | | `attributes` | _object_ | Any set of key: value pairs that add more details about a span. `duration.ms` is required, and the `name`, and `parent.id` attributes are strongly recommended to add. | yes | N/A | Requests without the required keys above will be rejected, and an [`NrIntegrationError`](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/trace-api-general-requirements-limits#response-validation) will be generated. ### The `common` object (optional) | field | type | description | required | default | | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | `attributes` | _object_ | Any set of key: value pairs that add common details about spans in the payload. If a span contains an attribute that has been set in `common`, the key in the span attributes object will take precedence. `duration.ms`, `name`, and `parent.id` are strongly recommended to add. | no | N/A | ### Highly recommended attributes [#recommended-attributes] While not required, these attributes should be included for the best experience with your data in the `attributes` object for each span. | attribute | default | description | | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `duration.ms` _float_ | none | Duration of this span in milliseconds. | | `name` _string_ | none | The name of this span. | | `parent.id` _string_ | none | The id of the caller of this span. Value is `null` if this is the [root span](https://docs.newrelic.com/docs/apm/distributed-tracing/ui-data/understand-use-distributed-tracing-data#trace-grouping). Traces without a root span will not be displayed. | | `service.name` _string_ | none | The name of the entity that created this span. If no value or an empty string is provided, the span is assigned to an "UNKNOWN" entity and will show as such in the UI. This value should be provided to get a complete experience in the UI. | ### Reserved attributes These attributes are currently reserved for internal New Relic usage. While they are not explicitly blocked, we recommend not using them. | attribute | default | description | | ---------------------- | -------------- | ------------------------------------------------------------------------------------------------ | | `entity.name` _string_ | `service.name` | This is derived from the `service.name` attribute. | | `entity.type` _string_ | `service` | The entity type is assumed to be a service. | | `entity.guid` _string_ | None | The `entity.guid` is a derived value that uniquely identifies the entity in New Relic's backend. | ### Other attributes You can add any arbitrary attributes you want in the `attributes` object in either `common` or each span object, with the exception of the [restricted attributes](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/trace-api-endpoint-requirements-limits#restricted-attributes). For example, you might want to add attributes like `customer.id` or `user.id` to help you analyze your trace data. Requirements and guidelines for trace JSON using the `newrelic` format: - Each JSON payload is an array of objects. - Each object should contain a required `spans` key. - Each object can contain an optional `common` key. Use this if you want to share information across multiple spans in a object. - Any keys on a span have precedence over the same key in the `common` block. - The value for a `spans` key is a list of `span` objects. - Certain attributes are [required](#required-attributes), and must be included either in the optional `common` block, or in each span. - Recommended and custom attributes can be optionally included in a list of key-value pairs under a key named `attributes`, in the optional `common` block and/or in each span. In the following example `POST`, there are two spans, both of which have the trace.id `12345` and the custom attribute `host: host123.example.com`. The first span has no `parent.id`, so that is the root of the trace; the second span's `parent.id` points to the ID of the first. ```json [ { "common": { "attributes": { "host": "host123.example.com" } }, "spans": [ { "trace.id": "12345", "id": "abc", "timestamp": 1603336834823, "attributes": { "user.email": "bob@newr.com", "service.name": "my-service", "duration.ms": 750, "name": "my-span" } }, { "trace.id": "12345", "id": "def", "timestamp": 1603336834899, "attributes": { "parent.id": "abc", "service.name": "second-service", "duration.ms": 750, "name": "second-span" } } ] } ] ``` To learn how to control how spans appear in New Relic (for example, adding errors or setting a span as a datastore span), see [Decorate spans](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/trace-api-decorate-spans-attributes). ## Explore more about distributed tracing: [#additional-help] - [Learn where Trace API data shows up in the UI](https://docs.newrelic.com/docs/understand-dependencies/distributed-tracing/ui-data/additional-distributed-tracing-features-new-relic-one#find-data). - [Learn how to decorate spans](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/trace-api-decorate-spans-attributes) for a richer, more detailed UI experience. For example, you can have spans show up as datastore spans or display errors. - Learn about general [data limits, required metadata, and response validation](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/trace-api-endpoint-requirements-limits). - If you don't see your trace data, see [Troubleshooting](https://docs.newrelic.com/docs/apm/distributed-tracing/trace-api/troubleshooting-missing-trace-api-data).