Facets are user-defined tags and attributes from your indexed logs. They are meant for either qualitative or quantitative data analysis. As such, you can use them in your Log Explorer to:
Note: You do not need facets to support log processing, livetail search, archive forwarding, rehydration, or metric generation from logs. You also do not need facets for routing logs through to Pipelines and Indexes with filters, or excluding or sampling logs from indexes with exclusion filters. In all these contexts, autocomplete capabilities rely on existing facets, but any input matching incoming logs would work.
Use qualitative facets when you need:
environmenttag to scope troubleshooting down to development, staging, or production environments.
http.network.client.geoip.country.iso_codeto see the top countries most impacted per number of 5XX errors on your NGINX web access logs, enriched with the Datadog GeoIP Processor.
user.emailfrom your Kong logs to know how many users connect every day to your website.
Qualitative facets can have a string or numerical (integer) type. While assigning string type to a dimension works in all case, using integer types on a dimension enables range filtering on top of all aforementioned capabilities. For instance,
http.status_code:[200 TO 299] is a valid query to use on a integer-type dimension. See search syntax for reference.
Use measures when you need:
Measures come with either a (long) integer or double value, for equivalent capabilities.
Measures support units in time or size for easier handling of orders of magnitude at query time and display time.
|BYTES||bit / byte / kibibyte / mebibyte / gibibyte / tebibyte / pebibyte / exbibyte|
|TIME||nanosecond / microsecond / millisecond / second / minute / hour / day / week|
Unit is a property of the measure itself, not of the field. For example, consider a
duration measure in nanoseconds: you have logs from
duration:1000 stands for 1000 milliseconds, and other logs from
duration:500 stands for 500 microseconds:
*1000000multiplier on logs from
service:A, and a
*1000multiplier on logs from
duration:>20ms(see search syntax for reference) to consistently query logs from both services at once, and see an aggregated result of max
The search bar provides the most comprehensive set of interactions to slice and dice your data. However, for most cases, the facet panel is likely to be a more straightforward way to navigate into your data. Open a facet to see a summary of its content for the scope of the current query.
Facets (qualitative) come with a top list of unique values, and a count of logs matching each of them:
Scope the search query clicking on either value. Clicking on a value toggles the search on this unique value and all values. Clicking on checkboxes adds or removes this specific value from the list of all values, you can also search upon its content:
Measures come with a slider indicating minimum and maximum values. Use the slider, or input numerical values, to scope the search query to different bounds.
Your organization has a whole collection of facets to address its comprehensive set of use cases across all different teams using logs. Most likely, however, only a subset of these facets is valuable to you in a specific troubleshooting context. Hide facets you don’t need on a routine basis, to keep only the most relevant facets for your troubleshooting sessions.
Hidden facets are still visible in the facet search (see the Filter Facet section) in case you need it. Unhide hidden facets from there.
Hidden facets are also hidden from auto-complete in the search bar, and drop down (such as measure, group-by) in analytics for the Log Explorer. However, hidden facets are still valid for search queries (in case you copy-paste a log-explorer link for instance).
Hidden facets have no impact aside from the log explorer (for instance: live tail, monitors, or widget definitions in dashboards).
Hiding facets is specific to your own troubleshooting context and won’t impact your teammates' view, unless you update a Saved View. Hidden facets is part of the context saved in a saved view.
Facets are grouped into meaningful themes, to ease navigation in the facet list. Assigning or reassigning a group for a facet (see how to manage facets) is only a matter of display in the facet list, and has no impact on search and analytics capabilities.
Use the search box on facets to scope down the whole facet list and jump more quickly to the very one you need to interact with. Facet search uses both facet display name and facet field name to scope down results.
Some facets may have been aliased (see the alias facet section). Aliased facets are still valid for slicing and dicing, but are considered deprecated by your organization:
When troubleshooting, it is more likely for you to find content from other teams (alongside content from your team) in the standard facet rather than the aliased facet. This makes correlation on content from diverse origins more straightforward.
If you see an aliased facet in your facet list, consider using the standard facet instead by clicking the switch to alias menu item. This action hides the aliased facet and unhides the standard facet. If doing so makes you update a saved view, consider saving the saved view so that the aliasing applies to everyone using this saved view.
You may wish to keep the non-standard aliased version of the facet if you are troubleshooting against old content (before the aliasing for this facet has been setup by your organization).
Most common facets such as
URL Path, or
Duration come out-of-the-box to start troubleshooting right away once your logs are flowing into log indexes.
The index facet is a specific facet that appears only if your organization has multiple indexes, and/or if you have active historical views. Use this facet if you want to scope down your query to a subset of your indexes.
As a matter of good practice, always consider using an existing facet rather than creating a new one (see the alias facets section). Using a unique facet for information of a similar nature fosters cross-team collaboration.
Note: Once a facet is created, its content is populated for all new logs flowing in either index. For an optimal usage of the Log Management solution, Datadog recommends using at most 1000 facets.
The easiest way to create a facet is to add it from the log side panel, where most of the facet details—such as the field name or the underlying type of data—are pre-filled and it’s only a matter of double-checking. Navigate in the Log Explorer to whichever log of interest bearing the field to create a facet on. Open the side-panel for this log, click on the corresponding field (either in tags or in attributes) and create a facet from there:
Note: As a best practice, it is recommended to use no more than 1000 facets.
In case finding a matching log is not an option, create a new facet directly from the facet panel using the add facet button.
Define the underlying field (key) name for this facet:
Autocomplete based on the content in logs 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 logs flowing in your indexes.
Gathering similar content under a unique facet enables cross-team analytics and eases cross-team troubleshooting—see Naming Convention for reference.
Use aliasing as an option to smoothly realign teams that rely on inconsistent naming conventions. With aliasing, you can have them all using the standard facet emerging for your organization.
This is the best option if multiple teams in your organization already created multiple facets for similar content.
When aliasing an aliased facet towards a standard facet:
To alias a facet towards a standard one, select the
Alias to... action item in the facet menu. Pick the destination facets from all the standard ones existing for your organization.
This is the best option if you onboard logs flowing from new sources. Rather than creating a facet for some field on those logs, and right after deprecating this facet by aliasing it to a standard facet, alias the field directly to an existing facet:
Additional helpful documentation, links, and articles: