Observability User Guide

The Trace Activity page in the Observability tool is where you can view active traces, search for specific traces, or create new trace configurations for your production environment data.

To learn more about the information that traces that provide, see trace details.

To find the Observability tool in the mParticle UI:

1. Log in to your mParticle account.
2. From the Overview page, select Observability within the Oversight suite.
3. This brings you to the Trace Activity page.

View all trace activity

The Trace Activity page displays a list of all recent traces for your development data, and any traces you have configured for your production data.

To view the details for a specific trace, click the purple ID under the Trace ID column.

Trace status

You can access a trace from Observability as soon as mParticle begins receiving and processing data, but it’s important to note that a trace can’t provide complete information about a data flow until all data in the trace has been fully processed. This typically occurs within 30 minutes.

Traces that are ready to be used for troubleshooting will display a “Complete” Trace Status on the Trace Details Page. Traces for data flows that are still being processed have a Trace Status of “In Progress”.

Sort and filter trace activity

You can filter your results by time frame by clicking the button labeled “Last 12 hours” and selecting one of the predefined date ranges or entering a custom range.

To further sort and filter your results, click Sort and Filters to view the following options:

Sort traces

Use the Order dropdown menu to sort your traces from most recent to oldest, or oldest to most recent.

Filter traces

Under Filters, select any of the following criteria to limit the traces displayed:

• Trace Type:

  • Event: displays only traces for the Events API
  • Identity: displays only traces for the IDSync API

• Result:

  • Success: displays only traces where all data was processed without any issues.
  • Insight: includes traces that experienced an interruption in data flow resulting from a configuration setting (such as a Rule or Filter).
  • Needs Attention: displays only traces that include an error message.
  • Warning: includes traces where an issue was encountered during data processing that could be resolved with a retry.

• Environment:

  • Production: displays only traces for data in your Production environment
  • Development: displays only traces for data in your Development environment
• mPID: filters results based on the MPID associated with a call to the IDSync API
• Inputs: filters results based on one of your configured data inputs
• Outputs: filters results based on one of your configured data outputs

After selecting your desired sorting and filter options, click Apply. This refreshes the Trace Activity page to display only filters matching your selected criteria.

Trace details

After opening the details page for a specific trace, you will see the following information:

Trace summary

• Trace ID: the unique ID for the trace.
• Trace Configuration ID: the ID of the trace configuration that the trace belongs to.
• mParticle ID: any MPID that is associated with the trace.
• Trace Status: either “In Progress” or “Complete”. The trace status indicates whether a trace contains enough information for it to be useful when troubleshooting your data flow. Traces that are “In Progress” indicate that the data being traced is still being processed. For more information, see Trace status.
• Trace Start Time: the date and time (in UTC) when the data was initially received by the mParticle platform.
• Duration: the total time elapsed during the trace.

Setup details

• Inputs: the name of the input configuration where the data originated.
• Output Configurations: the configured outputs for the data.
• Data plans: any active data plans that were used during processing.
• Environment: indicates whether the data flowed through your development or production environment.

Trace result

For each trace, you will see either Success, Insight, Needs Attention, or Warning displayed under “Result” along with any applicable messages under “Additional information”. You can use this information to determine whether an issue encountered during the trace was intentional or accidental, and what steps you may need to take to resolve any issues.

Message	Description
Success	Your data was ingested, processed, and forwarded without encountering any issues.
Insight	Your data flow was interrupted due to a configuration setting (such as a Rule or Filter). These interruptions may or may not be intentional, depending on your configuration and desired behavior. Referring to any insights can be helpful in identifying unintended consequences of a configuration setting.
Warning	Indicates that an issue was encountered during data processing that could be resolved with a retry.
Needs Attention	An error was encountered during the trace that cannot be resolved with a retry.

In some cases, you might see additional information with instructions to contact mParticle Support or your mParticle Account Representative, who can help you determine the root cause of an error or issue.

Related traces

It’s possible for one process to trigger other related processes in the mParticle platform. Any related processes that are traced will be listed here.

For example, when mParticle ingests a batch of event data or a request to make a bulk update to your data, each subsequent data flow will have its own unique trace, which you can find and access here.

Timeline view

The Timeline View provides a visual picture of how your data flows through the mParticle platform, broken into different spans, with each span representing a different stage of data processing.

Hover your cursor over the span in the timeline to see its exact start and end times.

To view details for a specific span, click on the span within the timeline and review the information panel at the bottom of the UI.

Not all spans will be presented sequentially, and some will appear to occur at the same time.

This is because mParticle executes different processes in parallel, to reduce the amount of time it takes to process your data. Most gaps between spans on your timeline are likely due to networking delays or internal processes that are not traced.

Span details

The Span Details view provides more granular information about a particular span. The details shown will vary depending on the span category.

To learn more about each span category, view the Span Glossary.

About trace IDs

Each individual trace is uniquely identified by a 36 character Trace ID resembling 66e0c0cd9bb8998a579595e42bae7077.

Trace IDs are essential for pinpointing specific data processing traces. You can find them in two primary ways:

1) Find a trace ID in an API response

Trace IDs are included with all responses to calls to the Events and IDSync APIs.

To find a trace ID in an API response:

1. Search your API response for the header titled X-MP-Trace-Id. The value of this header is the trace ID for the corresponding API call.

2) Find a trace ID in Live Stream

1. Log into your mParticle account and navigate to Activity > Live Stream.
2. Select any event row.
3. In the right hand sidebar, you will find the trace ID associated with that event.

Search for a trace using a trace ID

To search for a specific trace on the Trace Activity page:

1. Find and copy the trace ID from an API response or Live Stream as described in About trace IDs.
2. Log into your mParticle account and navigate to Oversight > Observability.
3. From the Trace Activity page, enter your trace ID in the search bar and click Search.

Open a trace from Live Stream

You can also view trace details for a data flow directly from the mParticle Live Stream.

1. Log into your mParticle account and navigate to Activity > Live Stream.
2. Select the event row you want to view the trace for.
3. In the right hand side bar, you will find the trace ID associated with that event.
4. Click on the Trace ID to open up the Trace Details page in the Observability suite.

Create a trace configuration

Trace configurations define the criteria for what production data you want traced.

To begin tracing data in your production environment, create a new trace configuration:

1. Navigate to Observability > Trace Configurations, and click Create Trace Configuration.

   

   This opens the Add Tracing Configuration window:

2. Under Inputs, select the connected data input you want to trace.
3. Use the date and time picker to select the Start Date & Time and Duration for your trace. Traces will only be generated after the start time and for the duration you specify.
4. Click Submit.

After clicking Submit, you will see your new tracing configuration listed on the Trace Configurations page, along with some general information about the trace configuration and one of the following statuses:

Active: traces are actively being generated for data ingested from the configured input. Pending: the start time set for the trace configuration is in the future. Once the scheduled start time is reached, the status will change to Active. Completed: the scheduled duration for the trace has elapsed and data is no longer being traced. Canceled: you have canceled the trace configuration