For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/dashboards/widgets/hostmap.md. A documentation index is available at /llms.txt.

Host Map Widget

The host map widget displays your infrastructure as a color-coded grid of hosts, containers, pods, or clusters. Use it to spot anomalies, understand resource distribution, and monitor infrastructure health at a glance. For the full-screen version, see the Host Map page.

Host map widget showing hosts grouped by availability zone and colored by CPU utilization, with darker hexagons indicating higher CPU usage.

Setup

Use Query Type to choose how the widget sources its data. Infrastructure (the default) queries infrastructure entities directly. DDSQL queries a published dataset instead.

Infrastructure mode

Host map widget configuration panel with the Query Type toggle set to Infrastructure, node type set to Host, fill by a CPU usage metric query, filter set to agent_version:<7.69.0, and grouped by agent_version.
  1. Node type: Choose which entity type to display: Host, Container, Pod, or Cluster.
  1. Fill by: Configure a metric query whose value determines the color of each node. The query is evaluated per node and mapped to the selected color palette.
  2. Filter by: Narrow the set of nodes using a tag filter expression (for example, env:prod). Filter expressions support wildcards and logical operators. Leave blank to include all nodes of the selected type.
  3. Group by: Aggregate nodes into hexagonal groups by one or more tags. Nodes that share a tag value appear together in the same group.
  4. Size by (optional): Configure a second metric query to scale the relative size of each node. Not available when a hierarchical child layer is configured.
  5. Style:
    • Palette: Choose a color palette.
    • Reverse palette: Flip the direction of the palette.
    • Min / Max: Pin the color scale to specific metric values. Nodes below the minimum display in the first palette color; nodes above the maximum display in the last.
  6. Visual Formatting Rules (optional): Apply color overrides to nodes whose fill value crosses a defined threshold.
  7. Hierarchical view (optional): Configure a child node type that appears when zooming into a group, such as Container within Host. The child layer has its own independent Fill by query and Style settings.

DDSQL mode

DDSQL mode maps the columns of a published dataset to the host map’s visualization, instead of querying infrastructure entities directly. Use it to visualize data that isn’t natively modeled as an infrastructure entity. Examples include a cost allocation breakdown or a custom topology defined by joining multiple sources.

Host map widget titled Deploy Error Spikes, showing 50 records as color-coded tiles ranging from light green (147 errors) to red (947 errors), based on a DDSQL query's error_count column.
Host map widget configuration panel with the Query Type toggle set to DDSQL, a published dataset selected, Display first set to 500, and Configure Points showing Label node by set to error_service and Fill by set to error_count.
  1. Query Type: Select DDSQL.
  2. Select a dataset published from the DDSQL Editor. Add a search query to filter its rows, and use Display first to choose the maximum number of rows to fetch from a list of presets, or enter a custom value. Click Preview Data to inspect the dataset’s columns and rows before mapping them.
  3. Under Configure Points, map dataset columns to visualization dimensions:
    • Label node by: A column whose values uniquely identify and label each point.
    • Fill by: A numeric column whose value determines the color of each point.
    • Size by (optional): A numeric column whose value scales the relative size of each point.
    • Group by (optional): Up to three columns whose values cluster points into nested groups. The order of the selected columns sets the nesting hierarchy: the first column forms the outermost group.
  4. Style and Visual Formatting Rules work the same way as in Infrastructure mode.

Options

Context links are enabled by default; you can toggle them on or off. Context links connect dashboard widgets with other pages (in Datadog or third-party).

API

This widget can be used with the Dashboards API. See the following table for the widget JSON schema definition:

Expand All

Field

Type

Description

custom_links

[object]

List of custom links.

is_hidden

boolean

The flag for toggling context menu link visibility.

label

string

The label for the custom link URL. Keep the label short and descriptive. Use metrics and tags as variables.

link

string

The URL of the custom link. URL must include http or https. A relative URL must start with /.

override_label

string

The label ID that refers to a context menu link. Can be logs, hosts, traces, profiles, processes, containers, or rum.

description

string

The description of the widget.

group

[string]

DEPRECATED: Deprecated - Only used by the legacy metric-based format. Use group_by (infrastructure) or a group dimension (DDSQL) inside requests instead.

no_group_hosts

boolean

DEPRECATED: Deprecated - Only used by the legacy metric-based format. Use no_group_hosts inside requests instead.

no_metric_hosts

boolean

DEPRECATED: Deprecated - Only used by the legacy metric-based format. Use no_metric_hosts inside requests instead.

node_type

enum

DEPRECATED: Deprecated - Only used by the legacy metric-based format. Use node_type inside requests instead. Allowed enum values: host,container

notes

string

Notes on the title.

requests [required]

object

Query definition for the host map widget. Supports three mutually exclusive formats distinguished by request_type: the deprecated legacy metric-based format (fill/size, no request_type), the infrastructure-backed format (request_type: infrastructure_hostmap), and the DDSQL published-dataset format (request_type: data_projection).

child

object

Optional child entities for hierarchical visualization (for example, host → container). Only used by the infrastructure-backed format.

child

object

Optional child request for hierarchical visualization (for example, hosts containing containers). Maximum one level of nesting.

conditional_formats

[object]

List of conditional formatting rules applied to fill values.

comparator [required]

enum

Comparator to apply. Allowed enum values: =,>,>=,<,<=

custom_bg_color

string

Color palette to apply to the background, same values available as palette.

custom_fg_color

string

Color palette to apply to the foreground, same values available as palette.

hide_value

boolean

True hides values.

image_url

string

Displays an image as the background.

metric

string

Metric from the request to correlate this conditional format with.

palette [required]

enum

Color palette to apply. Allowed enum values: blue,custom_bg,custom_image,custom_text,gray_on_white,grey,green,orange,red,red_on_white

Show 9 more,white_on_gray,white_on_green,green_on_white,white_on_red,white_on_yellow,yellow_on_white,black_on_light_yellow,black_on_light_green,black_on_light_red

timeframe

string

Defines the displayed timeframe.

value [required]

double

Value for the comparator.

enrichments [required]

[object]

Metric or event queries joined to the entity set. Each formula specifies a visual dimension.

formulas [required]

[object]

List of formulas that operate on queries, each assigned to a visual dimension.

alias

string

Expression alias.

dimension [required]

enum

Visual dimension for the host map widget. Used both by infrastructure-backed formulas and by DDSQL projection columns; group is only meaningful for DDSQL projection columns, where repeated entries define the grouping hierarchy. Allowed enum values: node,fill,size,group

formula [required]

string

String expression built from queries, formulas, and functions.

number_format

object

Number format options for the widget.

unit

 <oneOf>

Number format unit.

Option 1

object

Canonical unit.

per_unit_name

string

The name of the unit per item.

type

enum

The type of unit scale. Allowed enum values: canonical_unit

unit_name

string

The name of the unit.

Option 2

object

Custom unit.

label

string

The label for the custom unit.

type

enum

The type of custom unit. Allowed enum values: custom_unit_label

unit_scale

object

The definition of NumberFormatUnitScale object.

type

enum

The type of unit scale. Allowed enum values: canonical_unit

unit_name

string

The name of the unit.

queries [required]

[ <oneOf>]

List of queries that can be returned directly or used in formulas.

Option 1

object

A formula and functions metrics query.

aggregator

enum

The aggregation methods available for metrics queries. Allowed enum values: avg,min,max,sum,last,area,l2norm,percentile

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for metrics queries. Allowed enum values: metrics

name [required]

string

Name of the query for use in formulas.

query [required]

string

Metrics query definition.

semantic_mode

enum

Semantic mode for metrics queries. This determines how metrics from different sources are combined or displayed. Allowed enum values: combined,native

Option 2

object

A formula and functions events query.

compute [required]

object

Compute options.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

interval

int64

A time interval in milliseconds.

metric

string

Measurable attribute to compute.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for event platform-based queries. Allowed enum values: logs,spans,network,rum,security_signals,profiles,audit,events,ci_tests,ci_pipelines

Show 5 more,incident_analytics,product_analytics,on_call_events,errors,llm_observability

group_by

 <oneOf>

Group by configuration for a formula and functions events query. Accepts either a list of facet objects or a flat object that specifies a list of facet fields.

Option 1

[object]

List of objects used to group by.

facet [required]

string

Event facet.

limit

int64

Number of groups to return.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

Option 2

object

Flat group by configuration using multiple event facet fields.

fields [required]

[string]

List of event facets to group by.

limit

int64

Number of groups to return.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

indexes

[string]

An array of index names to query in the stream. Omit or use [] to query all indexes at once.

name [required]

string

Name of the query for use in formulas.

search

object

Search options.

query [required]

string

Events search string.

storage

string

Option for storage location. Feature in Private Beta.

Option 3

object

Process query using formulas and functions.

aggregator

enum

The aggregation methods available for metrics queries. Allowed enum values: avg,min,max,sum,last,area,l2norm,percentile

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data sources that rely on the process backend. Allowed enum values: process,container

is_normalized_cpu

boolean

Whether to normalize the CPU percentages.

limit

int64

Number of hits to return.

metric [required]

string

Process metric name.

name [required]

string

Name of query for use in formulas.

sort

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

tag_filters

[string]

An array of tags to filter by.

text_filter

string

Text to use as filter.

Option 4

object

A formula and functions APM dependency stats query.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for APM dependency stats queries. Allowed enum values: apm_dependency_stats

env [required]

string

APM environment.

is_upstream

boolean

Determines whether stats for upstream or downstream dependencies should be queried.

name [required]

string

Name of query to use in formulas.

operation_name [required]

string

Name of operation on service.

primary_tag_name

string

The name of the second primary tag used within APM; required when primary_tag_value is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog.

primary_tag_value

string

Filter APM data by the second primary tag. primary_tag_name must also be specified.

resource_name [required]

string

APM resource.

service [required]

string

APM service.

stat [required]

enum

APM statistic. Allowed enum values: avg_duration,avg_root_duration,avg_spans_per_trace,error_rate,pct_exec_time,pct_of_traces,total_traces_count

Option 5

object

DEPRECATED: APM resource stats query using formulas and functions. Deprecated - Use apm_metrics query type instead.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for APM resource stats queries. Allowed enum values: apm_resource_stats

env [required]

string

APM environment.

group_by

[string]

Array of fields to group results by.

name [required]

string

Name of this query to use in formulas.

operation_name

string

Name of operation on service.

primary_tag_name

string

Name of the second primary tag used within APM. Required when primary_tag_value is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog

primary_tag_value

string

Value of the second primary tag by which to filter APM data. primary_tag_name must also be specified.

resource_name

string

APM resource name.

service [required]

string

APM service name.

stat [required]

enum

APM resource stat name. Allowed enum values: errors,error_rate,hits,latency_avg,latency_distribution,latency_max,latency_p50,latency_p75,latency_p90,latency_p95

Show 1 more,latency_p99

Option 6

object

A formula and functions APM metrics query.

data_source [required]

enum

Data source for APM metrics queries. Allowed enum values: apm_metrics

group_by

[string]

Optional fields to group the query results by.

name [required]

string

Name of this query to use in formulas.

operation_mode

string

Optional operation mode to aggregate across operation names.

operation_name

string

Name of operation on service. If not provided, the primary operation name is used.

peer_tags

[string]

Tags to query for a specific downstream entity (peer.service, peer.db_instance, peer.s3, peer.s3.bucket, etc.).

query_filter

string

Additional filters for the query using metrics query syntax (e.g., env, primary_tag).

resource_hash

string

The hash of a specific resource to filter by.

resource_name

string

The full name of a specific resource to filter by.

service

string

APM service name.

span_kind

enum

Describes the relationship between the span, its parents, and its children in a trace. Allowed enum values: consumer,server,client,producer,internal

stat [required]

enum

APM metric stat name. Allowed enum values: errors,error_rate,errors_per_second,latency_avg,latency_max,latency_p50,latency_p75,latency_p90,latency_p95,latency_p99

Show 6 more,latency_p999,latency_distribution,hits,hits_per_second,total_time,apdex

Option 7

object

A formula and functions metrics query.

additional_query_filters

string

Additional filters applied to the SLO query.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for SLO measures queries. Allowed enum values: slo

group_mode

enum

Group mode to query measures. Allowed enum values: overall,components

measure [required]

enum

SLO measures queries. Allowed enum values: good_events,bad_events,good_minutes,bad_minutes,slo_status,error_budget_remaining,burn_rate,error_budget_burndown

name

string

Name of the query for use in formulas.

slo_id [required]

string

ID of an SLO to query measures.

slo_query_type

enum

Name of the query for use in formulas. Allowed enum values: metric,monitor,time_slice

Option 8

object

A formula and functions Cloud Cost query.

aggregator

enum

Aggregator used for the request. Allowed enum values: avg,last,max,min,sum,percentile

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for Cloud Cost queries. Allowed enum values: cloud_cost

name [required]

string

Name of the query for use in formulas.

query [required]

string

Query for Cloud Cost data.

Option 9

object

A formula and functions Product Analytics Extended query for advanced analytics features.

audience_filters

object

Product Analytics/RUM audience filters.

accounts

[object]

name

string

The name of the account subquery.

query

string

The query string for the account subquery.

filter_condition

string

An optional filter condition applied to the audience subquery.

segments

[object]

name

string

The name of the segment subquery.

segment_id

string

The unique identifier of the segment.

users

[object]

name

string

The name of the user subquery.

query

string

The query string for the user subquery.

compute [required]

object

Compute configuration for Product Analytics Extended queries.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

interval

double

Fixed-width time bucket interval in milliseconds for time series queries. Mutually exclusive with rollup.

metric

string

Measurable attribute to compute.

name

string

Name of the compute for use in formulas.

rollup

object

Calendar-aligned time bucket for time series queries (for example, day, week, or month boundaries). Mutually exclusive with interval.

alignment

string

Alignment of the interval. Valid values depend on the interval type. For day, use hours (for example, 1am, 2pm, or 14). For week, use day names (for example, monday). For month, use day-of-month ordinals (for example, 1st, 15th). For year or quarter, use month names (for example, january).

quantity

int64

Quantity of the interval.

timezone

string

Timezone for the interval.

type [required]

enum

Type of calendar interval. Allowed enum values: day,week,month,year,quarter,minute,hour

data_source [required]

enum

Data source for Product Analytics Extended queries. Allowed enum values: product_analytics_extended

group_by

[object]

Group by configuration.

facet [required]

string

Facet name to group by.

limit

int32

Maximum number of groups to return.

should_exclude_missing

boolean

Whether to exclude events missing the group-by facet.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

indexes

[string]

Event indexes to query.

name [required]

string

Name of the query for use in formulas.

query [required]

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

Option 10

object

A formula and functions User Journey query for defining funnel, timeseries, and scalar visualizations over journey data.

compute [required]

object

Compute configuration for User Journey formula queries.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

interval

double

Time bucket interval in milliseconds for time series queries.

metric

enum

Metric for User Journey formula compute. __dd.conversion and __dd.conversion_rate accept count and cardinality as aggregations. __dd.time_to_convert accepts avg, median, pc75, pc95, pc98, pc99, min, and max. Allowed enum values: __dd.conversion,__dd.conversion_rate,__dd.time_to_convert

target

object

Target for user journey search.

end

string

End value.

start

string

Start value.

type [required]

string

Target type.

value

string

Target value.

data_source [required]

enum

Data source for user journey funnel queries. Allowed enum values: product_analytics_journey

group_by

[object]

Group by configuration.

facet [required]

string

Facet name to group by.

limit

int32

Maximum number of groups to return.

should_exclude_missing

boolean

Whether to exclude events missing the group-by facet.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

target

object

Target for user journey search.

end

string

End value.

start

string

Start value.

type [required]

string

Target type.

value

string

Target value.

name [required]

string

Name of the query for use in formulas.

search [required]

object

User journey search configuration.

expression [required]

string

Expression string.

filters

object

Filters for user journey search.

audience_filters

object

Product Analytics/RUM audience filters.

accounts

[object]

name

string

The name of the account subquery.

query

string

The query string for the account subquery.

filter_condition

string

An optional filter condition applied to the audience subquery.

segments

[object]

name

string

The name of the segment subquery.

segment_id

string

The unique identifier of the segment.

users

[object]

name

string

The name of the user subquery.

query

string

The query string for the user subquery.

graph_filters

[object]

Graph filters.

name

string

Filter name.

operator

string

Filter operator.

target

object

Target for user journey search.

end

string

End value.

start

string

Start value.

type [required]

string

Target type.

value

string

Target value.

value

int64

Filter value.

string_filter

string

String filter.

join_keys

object

Join keys for user journey queries.

primary [required]

string

Primary join key.

secondary

[string]

Secondary join keys.

node_objects [required]

object

Node objects mapping.

<any-key>

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

step_aliases

object

Step aliases mapping.

<any-key>

string

Option 11

object

A formula and functions Retention query for defining timeseries and scalar visualizations.

compute [required]

object

Compute configuration for retention queries.

aggregation [required]

 <oneOf>

The type of aggregation that can be performed on events-based queries.

Option 1

enum

Standard aggregation types for events-based queries. Allowed enum values: avg,cardinality,count,delta,earliest,latest,max,median,min,most_frequent

Show 1 more,sum

Option 2

string

Percentile aggregation.

metric [required]

enum

Metric for retention compute. Allowed enum values: __dd.retention,__dd.retention_rate

data_source [required]

enum

Data source for retention queries. Allowed enum values: product_analytics_retention

group_by

[object]

Group by configuration.

facet [required]

string

Facet to group by.

limit

int64

Maximum number of groups.

should_exclude_missing

boolean

Whether to exclude missing values.

sort

object

Sort configuration for retention group by.

order

enum

Widget sorting methods. Allowed enum values: asc,desc

source

string

Source field.

target [required]

enum

Target for retention group by. Allowed enum values: cohort,return_period

name [required]

string

Name of the query for use in formulas.

search [required]

object

Search configuration for retention queries.

cohort_criteria [required]

object

Cohort criteria for retention queries.

base_query [required]

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

time_interval [required]

object

Time interval for cohort criteria.

type [required]

enum

Type of time interval for cohort criteria. Allowed enum values: calendar

value [required]

object

Calendar interval definition.

alignment

string

Alignment of the interval. Valid values depend on the interval type. For day, use hours (for example, 1am, 2pm, or 14). For week, use day names (for example, monday). For month, use day-of-month ordinals (for example, 1st, 15th). For year or quarter, use month names (for example, january).

quantity

int64

Quantity of the interval.

timezone

string

Timezone for the interval.

type [required]

enum

Type of calendar interval. Allowed enum values: day,week,month,year,quarter,minute,hour

filters

object

Filters for retention queries.

audience_filters

object

Product Analytics/RUM audience filters.

accounts

[object]

name

string

The name of the account subquery.

query

string

The query string for the account subquery.

filter_condition

string

An optional filter condition applied to the audience subquery.

segments

[object]

name

string

The name of the segment subquery.

segment_id

string

The unique identifier of the segment.

users

[object]

name

string

The name of the user subquery.

query

string

The query string for the user subquery.

string_filter

string

String filter.

retention_entity [required]

enum

Entity to track for retention. Allowed enum values: @usr.id,@account.id

return_condition [required]

enum

Condition for counting user return. Allowed enum values: conversion_on,conversion_on_or_after

return_criteria

object

Return criteria for retention queries.

base_query [required]

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

time_interval

object

Time interval for return criteria.

type [required]

enum

Type of time interval for return criteria. Allowed enum values: fixed

unit [required]

enum

Unit of time for retention return criteria interval. Allowed enum values: day,week,month

value [required]

double

Value of the time interval.

response_format [required]

enum

Response format for the scalar formula request. Only scalar is supported. Allowed enum values: scalar

filter

string

Filter string for the entity set in tag format (for example, env:prod).

group_by

[object]

Defines how entities are grouped into tiles. The ordering of entries implies the grouping hierarchy.

column [required]

string

Column name from the entity table (for example, cloud_provider, tags, labels).

key

string

Key within the column for nested attribute types (for example, service within tags).

no_group_hosts

boolean

Whether to hide entities that have no group assignment.

no_metric_hosts

boolean

Whether to hide entities that have no enrichment data.

node_type [required]

enum

Which type of infrastructure entity to visualize in the host map. Allowed enum values: host,container,pod,cluster

request_type [required]

enum

Identifies this as an infrastructure-backed host map request. Allowed enum values: infrastructure_hostmap

style

object

Style configuration for the infrastructure host map.

fill_max

double

Maximum value for the fill color scale. Omit to use automatic scaling.

fill_min

double

Minimum value for the fill color scale. Omit to use automatic scaling.

palette

string

Color palette name or alias.

palette_flip

boolean

Whether to invert the color palette.

conditional_formats

[object]

List of conditional formatting rules applied to fill values.

comparator [required]

enum

Comparator to apply. Allowed enum values: =,>,>=,<,<=

custom_bg_color

string

Color palette to apply to the background, same values available as palette.

custom_fg_color

string

Color palette to apply to the foreground, same values available as palette.

hide_value

boolean

True hides values.

image_url

string

Displays an image as the background.

metric

string

Metric from the request to correlate this conditional format with.

palette [required]

enum

Color palette to apply. Allowed enum values: blue,custom_bg,custom_image,custom_text,gray_on_white,grey,green,orange,red,red_on_white

Show 9 more,white_on_gray,white_on_green,green_on_white,white_on_red,white_on_yellow,yellow_on_white,black_on_light_yellow,black_on_light_green,black_on_light_red

timeframe

string

Defines the displayed timeframe.

value [required]

double

Value for the comparator.

enrichments [required]

[object]

Metric or event queries joined to the entity set. Each formula specifies a visual dimension.

formulas [required]

[object]

List of formulas that operate on queries, each assigned to a visual dimension.

alias

string

Expression alias.

dimension [required]

enum

Visual dimension for the host map widget. Used both by infrastructure-backed formulas and by DDSQL projection columns; group is only meaningful for DDSQL projection columns, where repeated entries define the grouping hierarchy. Allowed enum values: node,fill,size,group

formula [required]

string

String expression built from queries, formulas, and functions.

number_format

object

Number format options for the widget.

unit

 <oneOf>

Number format unit.

Option 1

object

Canonical unit.

per_unit_name

string

The name of the unit per item.

type

enum

The type of unit scale. Allowed enum values: canonical_unit

unit_name

string

The name of the unit.

Option 2

object

Custom unit.

label

string

The label for the custom unit.

type

enum

The type of custom unit. Allowed enum values: custom_unit_label

unit_scale

object

The definition of NumberFormatUnitScale object.

type

enum

The type of unit scale. Allowed enum values: canonical_unit

unit_name

string

The name of the unit.

queries [required]

[ <oneOf>]

List of queries that can be returned directly or used in formulas.

Option 1

object

A formula and functions metrics query.

aggregator

enum

The aggregation methods available for metrics queries. Allowed enum values: avg,min,max,sum,last,area,l2norm,percentile

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for metrics queries. Allowed enum values: metrics

name [required]

string

Name of the query for use in formulas.

query [required]

string

Metrics query definition.

semantic_mode

enum

Semantic mode for metrics queries. This determines how metrics from different sources are combined or displayed. Allowed enum values: combined,native

Option 2

object

A formula and functions events query.

compute [required]

object

Compute options.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

interval

int64

A time interval in milliseconds.

metric

string

Measurable attribute to compute.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for event platform-based queries. Allowed enum values: logs,spans,network,rum,security_signals,profiles,audit,events,ci_tests,ci_pipelines

Show 5 more,incident_analytics,product_analytics,on_call_events,errors,llm_observability

group_by

 <oneOf>

Group by configuration for a formula and functions events query. Accepts either a list of facet objects or a flat object that specifies a list of facet fields.

Option 1

[object]

List of objects used to group by.

facet [required]

string

Event facet.

limit

int64

Number of groups to return.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

Option 2

object

Flat group by configuration using multiple event facet fields.

fields [required]

[string]

List of event facets to group by.

limit

int64

Number of groups to return.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

indexes

[string]

An array of index names to query in the stream. Omit or use [] to query all indexes at once.

name [required]

string

Name of the query for use in formulas.

search

object

Search options.

query [required]

string

Events search string.

storage

string

Option for storage location. Feature in Private Beta.

Option 3

object

Process query using formulas and functions.

aggregator

enum

The aggregation methods available for metrics queries. Allowed enum values: avg,min,max,sum,last,area,l2norm,percentile

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data sources that rely on the process backend. Allowed enum values: process,container

is_normalized_cpu

boolean

Whether to normalize the CPU percentages.

limit

int64

Number of hits to return.

metric [required]

string

Process metric name.

name [required]

string

Name of query for use in formulas.

sort

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

tag_filters

[string]

An array of tags to filter by.

text_filter

string

Text to use as filter.

Option 4

object

A formula and functions APM dependency stats query.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for APM dependency stats queries. Allowed enum values: apm_dependency_stats

env [required]

string

APM environment.

is_upstream

boolean

Determines whether stats for upstream or downstream dependencies should be queried.

name [required]

string

Name of query to use in formulas.

operation_name [required]

string

Name of operation on service.

primary_tag_name

string

The name of the second primary tag used within APM; required when primary_tag_value is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog.

primary_tag_value

string

Filter APM data by the second primary tag. primary_tag_name must also be specified.

resource_name [required]

string

APM resource.

service [required]

string

APM service.

stat [required]

enum

APM statistic. Allowed enum values: avg_duration,avg_root_duration,avg_spans_per_trace,error_rate,pct_exec_time,pct_of_traces,total_traces_count

Option 5

object

DEPRECATED: APM resource stats query using formulas and functions. Deprecated - Use apm_metrics query type instead.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for APM resource stats queries. Allowed enum values: apm_resource_stats

env [required]

string

APM environment.

group_by

[string]

Array of fields to group results by.

name [required]

string

Name of this query to use in formulas.

operation_name

string

Name of operation on service.

primary_tag_name

string

Name of the second primary tag used within APM. Required when primary_tag_value is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog

primary_tag_value

string

Value of the second primary tag by which to filter APM data. primary_tag_name must also be specified.

resource_name

string

APM resource name.

service [required]

string

APM service name.

stat [required]

enum

APM resource stat name. Allowed enum values: errors,error_rate,hits,latency_avg,latency_distribution,latency_max,latency_p50,latency_p75,latency_p90,latency_p95

Show 1 more,latency_p99

Option 6

object

A formula and functions APM metrics query.

data_source [required]

enum

Data source for APM metrics queries. Allowed enum values: apm_metrics

group_by

[string]

Optional fields to group the query results by.

name [required]

string

Name of this query to use in formulas.

operation_mode

string

Optional operation mode to aggregate across operation names.

operation_name

string

Name of operation on service. If not provided, the primary operation name is used.

peer_tags

[string]

Tags to query for a specific downstream entity (peer.service, peer.db_instance, peer.s3, peer.s3.bucket, etc.).

query_filter

string

Additional filters for the query using metrics query syntax (e.g., env, primary_tag).

resource_hash

string

The hash of a specific resource to filter by.

resource_name

string

The full name of a specific resource to filter by.

service

string

APM service name.

span_kind

enum

Describes the relationship between the span, its parents, and its children in a trace. Allowed enum values: consumer,server,client,producer,internal

stat [required]

enum

APM metric stat name. Allowed enum values: errors,error_rate,errors_per_second,latency_avg,latency_max,latency_p50,latency_p75,latency_p90,latency_p95,latency_p99

Show 6 more,latency_p999,latency_distribution,hits,hits_per_second,total_time,apdex

Option 7

object

A formula and functions metrics query.

additional_query_filters

string

Additional filters applied to the SLO query.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for SLO measures queries. Allowed enum values: slo

group_mode

enum

Group mode to query measures. Allowed enum values: overall,components

measure [required]

enum

SLO measures queries. Allowed enum values: good_events,bad_events,good_minutes,bad_minutes,slo_status,error_budget_remaining,burn_rate,error_budget_burndown

name

string

Name of the query for use in formulas.

slo_id [required]

string

ID of an SLO to query measures.

slo_query_type

enum

Name of the query for use in formulas. Allowed enum values: metric,monitor,time_slice

Option 8

object

A formula and functions Cloud Cost query.

aggregator

enum

Aggregator used for the request. Allowed enum values: avg,last,max,min,sum,percentile

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for Cloud Cost queries. Allowed enum values: cloud_cost

name [required]

string

Name of the query for use in formulas.

query [required]

string

Query for Cloud Cost data.

Option 9

object

A formula and functions Product Analytics Extended query for advanced analytics features.

audience_filters

object

Product Analytics/RUM audience filters.

accounts

[object]

name

string

The name of the account subquery.

query

string

The query string for the account subquery.

filter_condition

string

An optional filter condition applied to the audience subquery.

segments

[object]

name

string

The name of the segment subquery.

segment_id

string

The unique identifier of the segment.

users

[object]

name

string

The name of the user subquery.

query

string

The query string for the user subquery.

compute [required]

object

Compute configuration for Product Analytics Extended queries.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

interval

double

Fixed-width time bucket interval in milliseconds for time series queries. Mutually exclusive with rollup.

metric

string

Measurable attribute to compute.

name

string

Name of the compute for use in formulas.

rollup

object

Calendar-aligned time bucket for time series queries (for example, day, week, or month boundaries). Mutually exclusive with interval.

alignment

string

Alignment of the interval. Valid values depend on the interval type. For day, use hours (for example, 1am, 2pm, or 14). For week, use day names (for example, monday). For month, use day-of-month ordinals (for example, 1st, 15th). For year or quarter, use month names (for example, january).

quantity

int64

Quantity of the interval.

timezone

string

Timezone for the interval.

type [required]

enum

Type of calendar interval. Allowed enum values: day,week,month,year,quarter,minute,hour

data_source [required]

enum

Data source for Product Analytics Extended queries. Allowed enum values: product_analytics_extended

group_by

[object]

Group by configuration.

facet [required]

string

Facet name to group by.

limit

int32

Maximum number of groups to return.

should_exclude_missing

boolean

Whether to exclude events missing the group-by facet.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

indexes

[string]

Event indexes to query.

name [required]

string

Name of the query for use in formulas.

query [required]

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

Option 10

object

A formula and functions User Journey query for defining funnel, timeseries, and scalar visualizations over journey data.

compute [required]

object

Compute configuration for User Journey formula queries.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

interval

double

Time bucket interval in milliseconds for time series queries.

metric

enum

Metric for User Journey formula compute. __dd.conversion and __dd.conversion_rate accept count and cardinality as aggregations. __dd.time_to_convert accepts avg, median, pc75, pc95, pc98, pc99, min, and max. Allowed enum values: __dd.conversion,__dd.conversion_rate,__dd.time_to_convert

target

object

Target for user journey search.

end

string

End value.

start

string

Start value.

type [required]

string

Target type.

value

string

Target value.

data_source [required]

enum

Data source for user journey funnel queries. Allowed enum values: product_analytics_journey

group_by

[object]

Group by configuration.

facet [required]

string

Facet name to group by.

limit

int32

Maximum number of groups to return.

should_exclude_missing

boolean

Whether to exclude events missing the group-by facet.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

target

object

Target for user journey search.

end

string

End value.

start

string

Start value.

type [required]

string

Target type.

value

string

Target value.

name [required]

string

Name of the query for use in formulas.

search [required]

object

User journey search configuration.

expression [required]

string

Expression string.

filters

object

Filters for user journey search.

audience_filters

object

Product Analytics/RUM audience filters.

accounts

[object]

name

string

The name of the account subquery.

query

string

The query string for the account subquery.

filter_condition

string

An optional filter condition applied to the audience subquery.

segments

[object]

name

string

The name of the segment subquery.

segment_id

string

The unique identifier of the segment.

users

[object]

name

string

The name of the user subquery.

query

string

The query string for the user subquery.

graph_filters

[object]

Graph filters.

name

string

Filter name.

operator

string

Filter operator.

target

object

Target for user journey search.

end

string

End value.

start

string

Start value.

type [required]

string

Target type.

value

string

Target value.

value

int64

Filter value.

string_filter

string

String filter.

join_keys

object

Join keys for user journey queries.

primary [required]

string

Primary join key.

secondary

[string]

Secondary join keys.

node_objects [required]

object

Node objects mapping.

<any-key>

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

step_aliases

object

Step aliases mapping.

<any-key>

string

Option 11

object

A formula and functions Retention query for defining timeseries and scalar visualizations.

compute [required]

object

Compute configuration for retention queries.

aggregation [required]

 <oneOf>

The type of aggregation that can be performed on events-based queries.

Option 1

enum

Standard aggregation types for events-based queries. Allowed enum values: avg,cardinality,count,delta,earliest,latest,max,median,min,most_frequent

Show 1 more,sum

Option 2

string

Percentile aggregation.

metric [required]

enum

Metric for retention compute. Allowed enum values: __dd.retention,__dd.retention_rate

data_source [required]

enum

Data source for retention queries. Allowed enum values: product_analytics_retention

group_by

[object]

Group by configuration.

facet [required]

string

Facet to group by.

limit

int64

Maximum number of groups.

should_exclude_missing

boolean

Whether to exclude missing values.

sort

object

Sort configuration for retention group by.

order

enum

Widget sorting methods. Allowed enum values: asc,desc

source

string

Source field.

target [required]

enum

Target for retention group by. Allowed enum values: cohort,return_period

name [required]

string

Name of the query for use in formulas.

search [required]

object

Search configuration for retention queries.

cohort_criteria [required]

object

Cohort criteria for retention queries.

base_query [required]

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

time_interval [required]

object

Time interval for cohort criteria.

type [required]

enum

Type of time interval for cohort criteria. Allowed enum values: calendar

value [required]

object

Calendar interval definition.

alignment

string

Alignment of the interval. Valid values depend on the interval type. For day, use hours (for example, 1am, 2pm, or 14). For week, use day names (for example, monday). For month, use day-of-month ordinals (for example, 1st, 15th). For year or quarter, use month names (for example, january).

quantity

int64

Quantity of the interval.

timezone

string

Timezone for the interval.

type [required]

enum

Type of calendar interval. Allowed enum values: day,week,month,year,quarter,minute,hour

filters

object

Filters for retention queries.

audience_filters

object

Product Analytics/RUM audience filters.

accounts

[object]

name

string

The name of the account subquery.

query

string

The query string for the account subquery.

filter_condition

string

An optional filter condition applied to the audience subquery.

segments

[object]

name

string

The name of the segment subquery.

segment_id

string

The unique identifier of the segment.

users

[object]

name

string

The name of the user subquery.

query

string

The query string for the user subquery.

string_filter

string

String filter.

retention_entity [required]

enum

Entity to track for retention. Allowed enum values: @usr.id,@account.id

return_condition [required]

enum

Condition for counting user return. Allowed enum values: conversion_on,conversion_on_or_after

return_criteria

object

Return criteria for retention queries.

base_query [required]

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

time_interval

object

Time interval for return criteria.

type [required]

enum

Type of time interval for return criteria. Allowed enum values: fixed

unit [required]

enum

Unit of time for retention return criteria interval. Allowed enum values: day,week,month

value [required]

double

Value of the time interval.

response_format [required]

enum

Response format for the scalar formula request. Only scalar is supported. Allowed enum values: scalar

filter

string

Filter string for the entity set in tag format (for example, env:prod).

group_by

[object]

Defines how entities are grouped into tiles. The ordering of entries implies the grouping hierarchy.

column [required]

string

Column name from the entity table (for example, cloud_provider, tags, labels).

key

string

Key within the column for nested attribute types (for example, service within tags).

no_group_hosts

boolean

Whether to hide entities that have no group assignment.

no_metric_hosts

boolean

Whether to hide entities that have no enrichment data.

node_type [required]

enum

Which type of infrastructure entity to visualize in the host map. Allowed enum values: host,container,pod,cluster

request_type [required]

enum

Identifies this as an infrastructure-backed host map request. Allowed enum values: infrastructure_hostmap

style

object

Style configuration for the infrastructure host map.

fill_max

double

Maximum value for the fill color scale. Omit to use automatic scaling.

fill_min

double

Minimum value for the fill color scale. Omit to use automatic scaling.

palette

string

Color palette name or alias.

palette_flip

boolean

Whether to invert the color palette.

conditional_formats

[object]

List of conditional formatting rules applied to fill values.

comparator [required]

enum

Comparator to apply. Allowed enum values: =,>,>=,<,<=

custom_bg_color

string

Color palette to apply to the background, same values available as palette.

custom_fg_color

string

Color palette to apply to the foreground, same values available as palette.

hide_value

boolean

True hides values.

image_url

string

Displays an image as the background.

metric

string

Metric from the request to correlate this conditional format with.

palette [required]

enum

Color palette to apply. Allowed enum values: blue,custom_bg,custom_image,custom_text,gray_on_white,grey,green,orange,red,red_on_white

Show 9 more,white_on_gray,white_on_green,green_on_white,white_on_red,white_on_yellow,yellow_on_white,black_on_light_yellow,black_on_light_green,black_on_light_red

timeframe

string

Defines the displayed timeframe.

value [required]

double

Value for the comparator.

enrichments

[object]

Metric or event queries joined to the entity set. Each formula specifies a visual dimension. Only used by the infrastructure-backed format.

formulas [required]

[object]

List of formulas that operate on queries, each assigned to a visual dimension.

alias

string

Expression alias.

dimension [required]

enum

Visual dimension for the host map widget. Used both by infrastructure-backed formulas and by DDSQL projection columns; group is only meaningful for DDSQL projection columns, where repeated entries define the grouping hierarchy. Allowed enum values: node,fill,size,group

formula [required]

string

String expression built from queries, formulas, and functions.

number_format

object

Number format options for the widget.

unit

 <oneOf>

Number format unit.

Option 1

object

Canonical unit.

per_unit_name

string

The name of the unit per item.

type

enum

The type of unit scale. Allowed enum values: canonical_unit

unit_name

string

The name of the unit.

Option 2

object

Custom unit.

label

string

The label for the custom unit.

type

enum

The type of custom unit. Allowed enum values: custom_unit_label

unit_scale

object

The definition of NumberFormatUnitScale object.

type

enum

The type of unit scale. Allowed enum values: canonical_unit

unit_name

string

The name of the unit.

queries [required]

[ <oneOf>]

List of queries that can be returned directly or used in formulas.

Option 1

object

A formula and functions metrics query.

aggregator

enum

The aggregation methods available for metrics queries. Allowed enum values: avg,min,max,sum,last,area,l2norm,percentile

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for metrics queries. Allowed enum values: metrics

name [required]

string

Name of the query for use in formulas.

query [required]

string

Metrics query definition.

semantic_mode

enum

Semantic mode for metrics queries. This determines how metrics from different sources are combined or displayed. Allowed enum values: combined,native

Option 2

object

A formula and functions events query.

compute [required]

object

Compute options.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

interval

int64

A time interval in milliseconds.

metric

string

Measurable attribute to compute.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for event platform-based queries. Allowed enum values: logs,spans,network,rum,security_signals,profiles,audit,events,ci_tests,ci_pipelines

Show 5 more,incident_analytics,product_analytics,on_call_events,errors,llm_observability

group_by

 <oneOf>

Group by configuration for a formula and functions events query. Accepts either a list of facet objects or a flat object that specifies a list of facet fields.

Option 1

[object]

List of objects used to group by.

facet [required]

string

Event facet.

limit

int64

Number of groups to return.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

Option 2

object

Flat group by configuration using multiple event facet fields.

fields [required]

[string]

List of event facets to group by.

limit

int64

Number of groups to return.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

indexes

[string]

An array of index names to query in the stream. Omit or use [] to query all indexes at once.

name [required]

string

Name of the query for use in formulas.

search

object

Search options.

query [required]

string

Events search string.

storage

string

Option for storage location. Feature in Private Beta.

Option 3

object

Process query using formulas and functions.

aggregator

enum

The aggregation methods available for metrics queries. Allowed enum values: avg,min,max,sum,last,area,l2norm,percentile

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data sources that rely on the process backend. Allowed enum values: process,container

is_normalized_cpu

boolean

Whether to normalize the CPU percentages.

limit

int64

Number of hits to return.

metric [required]

string

Process metric name.

name [required]

string

Name of query for use in formulas.

sort

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

tag_filters

[string]

An array of tags to filter by.

text_filter

string

Text to use as filter.

Option 4

object

A formula and functions APM dependency stats query.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for APM dependency stats queries. Allowed enum values: apm_dependency_stats

env [required]

string

APM environment.

is_upstream

boolean

Determines whether stats for upstream or downstream dependencies should be queried.

name [required]

string

Name of query to use in formulas.

operation_name [required]

string

Name of operation on service.

primary_tag_name

string

The name of the second primary tag used within APM; required when primary_tag_value is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog.

primary_tag_value

string

Filter APM data by the second primary tag. primary_tag_name must also be specified.

resource_name [required]

string

APM resource.

service [required]

string

APM service.

stat [required]

enum

APM statistic. Allowed enum values: avg_duration,avg_root_duration,avg_spans_per_trace,error_rate,pct_exec_time,pct_of_traces,total_traces_count

Option 5

object

DEPRECATED: APM resource stats query using formulas and functions. Deprecated - Use apm_metrics query type instead.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for APM resource stats queries. Allowed enum values: apm_resource_stats

env [required]

string

APM environment.

group_by

[string]

Array of fields to group results by.

name [required]

string

Name of this query to use in formulas.

operation_name

string

Name of operation on service.

primary_tag_name

string

Name of the second primary tag used within APM. Required when primary_tag_value is specified. See https://docs.datadoghq.com/tracing/guide/setting_primary_tags_to_scope/#add-a-second-primary-tag-in-datadog

primary_tag_value

string

Value of the second primary tag by which to filter APM data. primary_tag_name must also be specified.

resource_name

string

APM resource name.

service [required]

string

APM service name.

stat [required]

enum

APM resource stat name. Allowed enum values: errors,error_rate,hits,latency_avg,latency_distribution,latency_max,latency_p50,latency_p75,latency_p90,latency_p95

Show 1 more,latency_p99

Option 6

object

A formula and functions APM metrics query.

data_source [required]

enum

Data source for APM metrics queries. Allowed enum values: apm_metrics

group_by

[string]

Optional fields to group the query results by.

name [required]

string

Name of this query to use in formulas.

operation_mode

string

Optional operation mode to aggregate across operation names.

operation_name

string

Name of operation on service. If not provided, the primary operation name is used.

peer_tags

[string]

Tags to query for a specific downstream entity (peer.service, peer.db_instance, peer.s3, peer.s3.bucket, etc.).

query_filter

string

Additional filters for the query using metrics query syntax (e.g., env, primary_tag).

resource_hash

string

The hash of a specific resource to filter by.

resource_name

string

The full name of a specific resource to filter by.

service

string

APM service name.

span_kind

enum

Describes the relationship between the span, its parents, and its children in a trace. Allowed enum values: consumer,server,client,producer,internal

stat [required]

enum

APM metric stat name. Allowed enum values: errors,error_rate,errors_per_second,latency_avg,latency_max,latency_p50,latency_p75,latency_p90,latency_p95,latency_p99

Show 6 more,latency_p999,latency_distribution,hits,hits_per_second,total_time,apdex

Option 7

object

A formula and functions metrics query.

additional_query_filters

string

Additional filters applied to the SLO query.

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for SLO measures queries. Allowed enum values: slo

group_mode

enum

Group mode to query measures. Allowed enum values: overall,components

measure [required]

enum

SLO measures queries. Allowed enum values: good_events,bad_events,good_minutes,bad_minutes,slo_status,error_budget_remaining,burn_rate,error_budget_burndown

name

string

Name of the query for use in formulas.

slo_id [required]

string

ID of an SLO to query measures.

slo_query_type

enum

Name of the query for use in formulas. Allowed enum values: metric,monitor,time_slice

Option 8

object

A formula and functions Cloud Cost query.

aggregator

enum

Aggregator used for the request. Allowed enum values: avg,last,max,min,sum,percentile

cross_org_uuids

[string]

The source organization UUID for cross organization queries. Feature in Private Beta.

data_source [required]

enum

Data source for Cloud Cost queries. Allowed enum values: cloud_cost

name [required]

string

Name of the query for use in formulas.

query [required]

string

Query for Cloud Cost data.

Option 9

object

A formula and functions Product Analytics Extended query for advanced analytics features.

audience_filters

object

Product Analytics/RUM audience filters.

accounts

[object]

name

string

The name of the account subquery.

query

string

The query string for the account subquery.

filter_condition

string

An optional filter condition applied to the audience subquery.

segments

[object]

name

string

The name of the segment subquery.

segment_id

string

The unique identifier of the segment.

users

[object]

name

string

The name of the user subquery.

query

string

The query string for the user subquery.

compute [required]

object

Compute configuration for Product Analytics Extended queries.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

interval

double

Fixed-width time bucket interval in milliseconds for time series queries. Mutually exclusive with rollup.

metric

string

Measurable attribute to compute.

name

string

Name of the compute for use in formulas.

rollup

object

Calendar-aligned time bucket for time series queries (for example, day, week, or month boundaries). Mutually exclusive with interval.

alignment

string

Alignment of the interval. Valid values depend on the interval type. For day, use hours (for example, 1am, 2pm, or 14). For week, use day names (for example, monday). For month, use day-of-month ordinals (for example, 1st, 15th). For year or quarter, use month names (for example, january).

quantity

int64

Quantity of the interval.

timezone

string

Timezone for the interval.

type [required]

enum

Type of calendar interval. Allowed enum values: day,week,month,year,quarter,minute,hour

data_source [required]

enum

Data source for Product Analytics Extended queries. Allowed enum values: product_analytics_extended

group_by

[object]

Group by configuration.

facet [required]

string

Facet name to group by.

limit

int32

Maximum number of groups to return.

should_exclude_missing

boolean

Whether to exclude events missing the group-by facet.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

indexes

[string]

Event indexes to query.

name [required]

string

Name of the query for use in formulas.

query [required]

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

Option 10

object

A formula and functions User Journey query for defining funnel, timeseries, and scalar visualizations over journey data.

compute [required]

object

Compute configuration for User Journey formula queries.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

interval

double

Time bucket interval in milliseconds for time series queries.

metric

enum

Metric for User Journey formula compute. __dd.conversion and __dd.conversion_rate accept count and cardinality as aggregations. __dd.time_to_convert accepts avg, median, pc75, pc95, pc98, pc99, min, and max. Allowed enum values: __dd.conversion,__dd.conversion_rate,__dd.time_to_convert

target

object

Target for user journey search.

end

string

End value.

start

string

Start value.

type [required]

string

Target type.

value

string

Target value.

data_source [required]

enum

Data source for user journey funnel queries. Allowed enum values: product_analytics_journey

group_by

[object]

Group by configuration.

facet [required]

string

Facet name to group by.

limit

int32

Maximum number of groups to return.

should_exclude_missing

boolean

Whether to exclude events missing the group-by facet.

sort

object

Options for sorting group by results.

aggregation [required]

enum

Aggregation methods for event platform queries. Allowed enum values: count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min

Show 2 more,max,avg

metric

string

Metric used for sorting group by results.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

target

object

Target for user journey search.

end

string

End value.

start

string

Start value.

type [required]

string

Target type.

value

string

Target value.

name [required]

string

Name of the query for use in formulas.

search [required]

object

User journey search configuration.

expression [required]

string

Expression string.

filters

object

Filters for user journey search.

audience_filters

object

Product Analytics/RUM audience filters.

accounts

[object]

name

string

The name of the account subquery.

query

string

The query string for the account subquery.

filter_condition

string

An optional filter condition applied to the audience subquery.

segments

[object]

name

string

The name of the segment subquery.

segment_id

string

The unique identifier of the segment.

users

[object]

name

string

The name of the user subquery.

query

string

The query string for the user subquery.

graph_filters

[object]

Graph filters.

name

string

Filter name.

operator

string

Filter operator.

target

object

Target for user journey search.

end

string

End value.

start

string

Start value.

type [required]

string

Target type.

value

string

Target value.

value

int64

Filter value.

string_filter

string

String filter.

join_keys

object

Join keys for user journey queries.

primary [required]

string

Primary join key.

secondary

[string]

Secondary join keys.

node_objects [required]

object

Node objects mapping.

<any-key>

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

step_aliases

object

Step aliases mapping.

<any-key>

string

Option 11

object

A formula and functions Retention query for defining timeseries and scalar visualizations.

compute [required]

object

Compute configuration for retention queries.

aggregation [required]

 <oneOf>

The type of aggregation that can be performed on events-based queries.

Option 1

enum

Standard aggregation types for events-based queries. Allowed enum values: avg,cardinality,count,delta,earliest,latest,max,median,min,most_frequent

Show 1 more,sum

Option 2

string

Percentile aggregation.

metric [required]

enum

Metric for retention compute. Allowed enum values: __dd.retention,__dd.retention_rate

data_source [required]

enum

Data source for retention queries. Allowed enum values: product_analytics_retention

group_by

[object]

Group by configuration.

facet [required]

string

Facet to group by.

limit

int64

Maximum number of groups.

should_exclude_missing

boolean

Whether to exclude missing values.

sort

object

Sort configuration for retention group by.

order

enum

Widget sorting methods. Allowed enum values: asc,desc

source

string

Source field.

target [required]

enum

Target for retention group by. Allowed enum values: cohort,return_period

name [required]

string

Name of the query for use in formulas.

search [required]

object

Search configuration for retention queries.

cohort_criteria [required]

object

Cohort criteria for retention queries.

base_query [required]

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

time_interval [required]

object

Time interval for cohort criteria.

type [required]

enum

Type of time interval for cohort criteria. Allowed enum values: calendar

value [required]

object

Calendar interval definition.

alignment

string

Alignment of the interval. Valid values depend on the interval type. For day, use hours (for example, 1am, 2pm, or 14). For week, use day names (for example, monday). For month, use day-of-month ordinals (for example, 1st, 15th). For year or quarter, use month names (for example, january).

quantity

int64

Quantity of the interval.

timezone

string

Timezone for the interval.

type [required]

enum

Type of calendar interval. Allowed enum values: day,week,month,year,quarter,minute,hour

filters

object

Filters for retention queries.

audience_filters

object

Product Analytics/RUM audience filters.

accounts

[object]

name

string

The name of the account subquery.

query

string

The query string for the account subquery.

filter_condition

string

An optional filter condition applied to the audience subquery.

segments

[object]

name

string

The name of the segment subquery.

segment_id

string

The unique identifier of the segment.

users

[object]

name

string

The name of the user subquery.

query

string

The query string for the user subquery.

string_filter

string

String filter.

retention_entity [required]

enum

Entity to track for retention. Allowed enum values: @usr.id,@account.id

return_condition [required]

enum

Condition for counting user return. Allowed enum values: conversion_on,conversion_on_or_after

return_criteria

object

Return criteria for retention queries.

base_query [required]

object

Base query for Product Analytics.

data_source [required]

enum

Data source for Product Analytics event queries. Allowed enum values: product_analytics

search [required]

object

Search configuration for Product Analytics event query.

query [required]

string

RUM event search query used to filter views or actions.

time_interval

object

Time interval for return criteria.

type [required]

enum

Type of time interval for return criteria. Allowed enum values: fixed

unit [required]

enum

Unit of time for retention return criteria interval. Allowed enum values: day,week,month

value [required]

double

Value of the time interval.

response_format [required]

enum

Response format for the scalar formula request. Only scalar is supported. Allowed enum values: scalar

fill

object

DEPRECATED: Deprecated - Legacy metric-based format. Use the infrastructure-backed (request_type: infrastructure_hostmap) or DDSQL (request_type: data_projection) format instead.

apm_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

event_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

log_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

network_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

process_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

filter_by

[string]

List of processes.

limit

int64

Max number of items in the filter list.

metric [required]

string

Your chosen metric.

search_by

string

Your chosen search term.

profile_metrics_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

q

string

Query definition.

rum_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

security_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

filter

string

Filter string for the entity set in tag format (for example, env:prod). Only used by the infrastructure-backed format.

group_by

[object]

Defines how entities are grouped into tiles. The ordering of entries implies the grouping hierarchy. Only used by the infrastructure-backed format.

column [required]

string

Column name from the entity table (for example, cloud_provider, tags, labels).

key

string

Key within the column for nested attribute types (for example, service within tags).

limit

int64

Maximum number of rows to return from the dataset query. Only used by the DDSQL format.

no_group_hosts

boolean

Whether to hide entities that have no group assignment.

no_metric_hosts

boolean

Whether to hide entities that have no enrichment data.

node_type

enum

Entity type to visualize. Only used by the infrastructure-backed format. Allowed enum values: host,container,pod,cluster

projection

object

Maps dataset columns to map dimensions (entity, optional parent for grouping, fill, size). Only used by the DDSQL format.

dimensions [required]

[object]

List of column-to-dimension mappings for the projection.

alias

string

Alias used to label the column instead of its name.

column [required]

string

Source column name from the dataset.

dimension [required]

enum

Visual dimension for the host map widget. Used both by infrastructure-backed formulas and by DDSQL projection columns; group is only meaningful for DDSQL projection columns, where repeated entries define the grouping hierarchy. Allowed enum values: node,fill,size,group

number_format

object

Number format options for the widget.

unit

 <oneOf>

Number format unit.

Option 1

object

Canonical unit.

per_unit_name

string

The name of the unit per item.

type

enum

The type of unit scale. Allowed enum values: canonical_unit

unit_name

string

The name of the unit.

Option 2

object

Custom unit.

label

string

The label for the custom unit.

type

enum

The type of custom unit. Allowed enum values: custom_unit_label

unit_scale

object

The definition of NumberFormatUnitScale object.

type

enum

The type of unit scale. Allowed enum values: canonical_unit

unit_name

string

The name of the unit.

type [required]

enum

Type of the host map projection. Allowed enum values: hostmap

query

object

Published-dataset query. Only used by the DDSQL format.

data_source [required]

enum

Identifies this as a published-dataset list query. Allowed enum values: dataset

dataset_id [required]

string

ID of the published dataset to query.

dataset_provider [required]

enum

Product page that published the dataset queried by a DatasetListQuery. ddsql_query is the only provider currently supported for host map widgets. Allowed enum values: ddsql_query

filter

string

Filter applied to the dataset's rows, using events-style search syntax.

limit

int64

Maximum number of rows to return from the dataset query.

sort

object

Sort configuration for a DatasetListQuery.

fields [required]

[object]

List of fields to sort the rows by, applied in order.

name [required]

string

Name of the field to sort on.

order [required]

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

request_type

enum

Identifies which host map request format the sibling fields on HostMapWidgetDefinitionRequests describe: an infrastructure-backed request or a DDSQL published-dataset request. Allowed enum values: infrastructure_hostmap,data_projection

size

object

DEPRECATED: Deprecated - Legacy metric-based format. Use the infrastructure-backed (request_type: infrastructure_hostmap) or DDSQL (request_type: data_projection) format instead.

apm_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

event_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

log_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

network_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

process_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

filter_by

[string]

List of processes.

limit

int64

Max number of items in the filter list.

metric [required]

string

Your chosen metric.

search_by

string

Your chosen search term.

profile_metrics_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

q

string

Query definition.

rum_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

security_query

object

DEPRECATED: Deprecated - Use queries and formulas instead.

compute

object

Define computation for a log query.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

group_by

[object]

List of tag prefixes to group by in the case of a cluster check.

facet [required]

string

Facet name.

limit

int64

Maximum number of items in the group.

sort

object

Define a sorting method.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

order [required]

enum

Widget sorting methods. Allowed enum values: asc,desc

index

string

A coma separated-list of index names. Use "*" query all indexes at once. Multiple Indexes

multi_compute

[object]

This field is mutually exclusive with compute.

aggregation [required]

string

The aggregation method.

facet

string

Facet name.

interval

int64

Define a time interval in seconds.

search

object

The query being made on the logs.

query [required]

string

Search value to apply.

style

object

Style configuration for the infrastructure host map.

fill_max

double

Maximum value for the fill color scale. Omit to use automatic scaling.

fill_min

double

Minimum value for the fill color scale. Omit to use automatic scaling.

palette

string

Color palette name or alias.

palette_flip

boolean

Whether to invert the color palette.

scope

[string]

DEPRECATED: Deprecated - Only used by the legacy metric-based format. Use filter inside requests instead.

style

object

DEPRECATED: Deprecated - Only used by the legacy metric-based format. Use style inside requests instead.

fill_max

string

Max value to use to color the map.

fill_min

string

Min value to use to color the map.

palette

string

Color palette to apply to the widget.

palette_flip

boolean

Whether to flip the palette tones.

title

string

Title of the widget.

title_align

enum

How to align the text on the widget. Allowed enum values: center,left,right

title_size

string

Size of the title.

type [required]

enum

Type of the host map widget. Allowed enum values: hostmap

default: hostmap

{
  "custom_links": [
    {
      "is_hidden": false,
      "label": "Search logs for {{host}}",
      "link": "https://app.datadoghq.com/logs?query={{host}}",
      "override_label": "logs"
    }
  ],
  "description": "string",
  "group": [],
  "no_group_hosts": false,
  "no_metric_hosts": false,
  "node_type": "string",
  "notes": "string",
  "requests": {
    "child": {
      "child": {
        "conditional_formats": [
          {
            "comparator": ">",
            "custom_bg_color": "string",
            "custom_fg_color": "string",
            "hide_value": false,
            "image_url": "string",
            "metric": "string",
            "palette": "blue",
            "timeframe": "string",
            "value": 0
          }
        ],
        "enrichments": [
          {
            "formulas": [
              {
                "alias": "my-metric",
                "dimension": "node",
                "formula": "query1",
                "number_format": {
                  "unit": {
                    "per_unit_name": "bytes",
                    "type": "canonical_unit",
                    "unit_name": "bytes"
                  },
                  "unit_scale": {
                    "type": "canonical_unit",
                    "unit_name": "bytes"
                  }
                }
              }
            ],
            "queries": [
              []
            ],
            "response_format": "scalar"
          }
        ],
        "filter": "env:prod",
        "group_by": [
          {
            "column": "tags",
            "key": "service"
          }
        ],
        "no_group_hosts": false,
        "no_metric_hosts": false,
        "node_type": "host",
        "request_type": "infrastructure_hostmap",
        "style": {
          "fill_max": "number",
          "fill_min": "number",
          "palette": "hostmap_blues",
          "palette_flip": false
        }
      },
      "conditional_formats": [
        {
          "comparator": ">",
          "custom_bg_color": "string",
          "custom_fg_color": "string",
          "hide_value": false,
          "image_url": "string",
          "metric": "string",
          "palette": "blue",
          "timeframe": "string",
          "value": 0
        }
      ],
      "enrichments": [
        {
          "formulas": [
            {
              "alias": "my-metric",
              "dimension": "node",
              "formula": "query1",
              "number_format": {
                "unit": {
                  "per_unit_name": "bytes",
                  "type": "canonical_unit",
                  "unit_name": "bytes"
                },
                "unit_scale": {
                  "type": "canonical_unit",
                  "unit_name": "bytes"
                }
              }
            }
          ],
          "queries": [
            []
          ],
          "response_format": "scalar"
        }
      ],
      "filter": "env:prod",
      "group_by": [
        {
          "column": "tags",
          "key": "service"
        }
      ],
      "no_group_hosts": false,
      "no_metric_hosts": false,
      "node_type": "host",
      "request_type": "infrastructure_hostmap",
      "style": {
        "fill_max": "number",
        "fill_min": "number",
        "palette": "hostmap_blues",
        "palette_flip": false
      }
    },
    "conditional_formats": [
      {
        "comparator": ">",
        "custom_bg_color": "string",
        "custom_fg_color": "string",
        "hide_value": false,
        "image_url": "string",
        "metric": "string",
        "palette": "blue",
        "timeframe": "string",
        "value": 0
      }
    ],
    "enrichments": [
      {
        "formulas": [
          {
            "alias": "my-metric",
            "dimension": "node",
            "formula": "query1",
            "number_format": {
              "unit": {
                "per_unit_name": "bytes",
                "type": "canonical_unit",
                "unit_name": "bytes"
              },
              "unit_scale": {
                "type": "canonical_unit",
                "unit_name": "bytes"
              }
            }
          }
        ],
        "queries": [
          []
        ],
        "response_format": "scalar"
      }
    ],
    "fill": {
      "apm_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "event_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "log_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "network_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "process_query": {
        "filter_by": [],
        "limit": "integer",
        "metric": "system.load.1",
        "search_by": "string"
      },
      "profile_metrics_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "q": "string",
      "rum_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "security_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      }
    },
    "filter": "env:prod",
    "group_by": [
      {
        "column": "tags",
        "key": "service"
      }
    ],
    "limit": "integer",
    "no_group_hosts": false,
    "no_metric_hosts": false,
    "node_type": "host",
    "projection": {
      "dimensions": [
        {
          "alias": "string",
          "column": "entity_id",
          "dimension": "node",
          "number_format": {
            "unit": {
              "per_unit_name": "bytes",
              "type": "canonical_unit",
              "unit_name": "bytes"
            },
            "unit_scale": {
              "type": "canonical_unit",
              "unit_name": "bytes"
            }
          }
        }
      ],
      "type": "hostmap"
    },
    "query": {
      "data_source": "dataset",
      "dataset_id": "abc-123-def",
      "dataset_provider": "ddsql_query",
      "filter": "service:web-store",
      "limit": "integer",
      "sort": {
        "fields": [
          {
            "name": "duration",
            "order": "asc"
          }
        ]
      }
    },
    "request_type": "infrastructure_hostmap",
    "size": {
      "apm_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "event_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "log_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "network_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "process_query": {
        "filter_by": [],
        "limit": "integer",
        "metric": "system.load.1",
        "search_by": "string"
      },
      "profile_metrics_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "q": "string",
      "rum_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      },
      "security_query": {
        "compute": {
          "aggregation": "avg",
          "facet": "@duration",
          "interval": 5000
        },
        "group_by": [
          {
            "facet": "resource_name",
            "limit": 50,
            "sort": {
              "aggregation": "avg",
              "facet": "@string_query.interval",
              "order": "desc"
            }
          }
        ],
        "index": "days-3,days-7",
        "multi_compute": [
          {
            "aggregation": "avg",
            "facet": "@duration",
            "interval": 5000
          }
        ],
        "search": {
          "query": ""
        }
      }
    },
    "style": {
      "fill_max": "number",
      "fill_min": "number",
      "palette": "hostmap_blues",
      "palette_flip": false
    }
  },
  "scope": [],
  "style": {
    "fill_max": "string",
    "fill_min": "string",
    "palette": "string",
    "palette_flip": false
  },
  "title": "string",
  "title_align": "string",
  "title_size": "string",
  "type": "hostmap"
}

Further Reading

Additional helpful documentation, links, and articles:

Host MapDOCUMENTATION more more Building Dashboards using JSONDOCUMENTATION more more DDSQL EditorDOCUMENTATION more more