Span Facets

Cette page n'est pas encore disponible en français, sa traduction est en cours.
Si vous avez des questions ou des retours sur notre projet de traduction actuel, n'hésitez pas à nous contacter.

Overview

Facets are user-defined tags and attributes from your spans. They are useful for both qualitative and quantitative data analysis. You can use facets in the Trace Explorer to:

Facets also allow you to manipulate spans in your trace analytics monitors, and in APM queries that appear on dashboards and in notebooks.

Facets panel

Note: Creating facets is not required to search spans, to generate metrics from spans, or to index spans with retention filters. In all these contexts, autocomplete capabilities do use existing facets, but also any input that matches incoming spans also works.

Qualitative facets

Use qualitative facets when you need to:

  • Get relative insights for values. For example, create a facet on a datacenter span tag to scope down the investigation to one specific region when slow requests are detected.

  • Count unique values. For example, create a facet on usr.email to see how many distinct users experience errors while loading a specific resource.

  • Frequently filter your spans against particular values. For example, create a facet on an environment tag to scope troubleshooting down to development, staging, or production environments.

    Note: Although facets are not required for filtering on tags, defining facets for tags that you often use during investigations can help reduce your time to resolution.

Quantitative facets (measures)

Use measures when you need to:

  • Aggregate values from multiple traces. For example, create a measure on the number of rows in Cassandra and view the p95 or top-most referrers per sum of file size requested.
  • Numerically compute the highest latency services, for example, for shopping cart values over $1000.
  • Filter continuous values, for example, the size in bytes of each payload chunk of a video stream.

Measure types

Measures have either a (long) integer or double value, for equivalent capabilities.

Units

Measures support units (time in seconds or size in bytes) for handling of orders of magnitude at query time and display time. The unit is a property of the measure itself, not of the field.

For example, consider a duration measure in nanoseconds. Suppose spans from service:A have duration:1000, meaning 1000 milliseconds. Supposed spans from service:B have duration:500, meaning 500 microseconds. Use duration:>20ms to consistently query span tags from both services at once. Read query syntax for more reference information about queries.

Facet panel

The search bar provides the most comprehensive set of interactions to filter and group your data. However, for many cases, the facet panel is a straightforward way to navigate into your data. Open a facet to see a summary of its content for the scope of the current query.

The search bar and URL automatically reflect your selections from the facet panel.

  • Facets (qualitative) come with a top list of unique values, and a count of spans matching each of them.
  • Measures (quantitative) come with a slider indicating minimum and maximum values. Use the slider, or input numerical values, to scope the search query to different bounds.

Hiding facets

Your organization has many facets to address use cases across the various teams that use traces. Most likely, only a subset of these facets is valuable to you in a specific troubleshooting context.

Hide facets that you don’t need on a routine basis, to keep only the most relevant facets for your troubleshooting sessions.

Hide Facet

Hidden facets are still visible in the facet search (see the Filter Facet section) in case you need it. Unhide hidden facets from facet search.

Unhide Facet

Hidden facets and teammates

Hiding facets is specific to your own troubleshooting context and does not impact your teammates’ view, unless you update a saved view. Hidden facets is part of the context saved in a saved view.

Grouping facets

Facets are grouped into meaningful themes, to ease navigation in the facet list. Assigning or reassigning a group for a facet (see Managing facets) affects only the facet list, and has no impact on search and analytics.

Group Facets

Filtering facets

Use the search facets box on the facet panel to scope the whole facet list and navigate more quickly to the one facet you need to interact with. Search facets uses both facet display name and facet field name to scope results.

Search Facet

Managing facets

Out-of-the-box facets

Most common facets such as Status and Service come out-of-the-box, so you can start troubleshooting right away once your spans are ingested.

Creating facets

As a matter of good practice, consider reusing an existing facet rather than creating a new one. Using a single facet for information of a similar nature fosters cross-team collaboration.

Creating facets from the trace side panel

The easiest way to create a facet is to add it from the trace side panel, so that most of the facet details (field path, underlying type) are pre-filled. Navigate in the Trace Explorer a span of interest that contains the field to create a facet on. Open the trace side-panel for this span by selecting the span from the list. Click on the desired field (either in span tags or in infrastructure tags) and create a facet from there:

  • If the field has a numerical value, you can create either a facet or a measure.
  • If the field has a string value, only facet creation is available.
Add Facet from tags

Creating facets from the facet list

If finding a span that has the desired field is not an option, create a facet directly from the facet panel by clicking + Add.

Define the underlying field (key) name for this facet:

  • Use tag key name for infrastructure tags.
  • Use the attribute path for span attributes, with @ prefix.

Autocomplete based on the content in spans of the current views helps you to define the proper field name. But you can use virtually any value here, specifically in the case that you don’t yet have matching spans received by Datadog.

Add Facet from scratch

Further Reading

Documentation, liens et articles supplémentaires utiles: