Datadog에서 와일드카드 위젯과 Vega-Lite 사용하기

원문 보기 위키 갱신 2026.10.05

Datadog에서 와일드카드 위젯과 함께 Vega-Lite를 사용하면, Datadog에만 고유한 Vega-Lite 스펙 확장을 발견하게 돼요. 이 가이드는 Datadog의 고유 스펙과의 호환성을 보장하면서 Vega-Lite를 데이터 시각화에 효과적으로 사용하기 위한 필요한 구성과 고려 사항을 설명합니다.

출처: 문서

본문

개요

Datadog에서 와일드카드 위젯과 함께 Vega-Lite를 사용하면, Datadog에만 고유한 Vega-Lite 스펙 확장을 발견하게 돼요. 이 가이드는 이러한 고유 스펙과의 호환성을 보장하면서 Vega-Lite를 Datadog의 데이터 시각화에 효과적으로 사용하기 위한 필요한 구성과 고려 사항을 설명해요. 이 스펙을 이해하고 활용하면, 테마 선호도에 효과적이고 반응적으로 맞춰진 시각적으로 매력적이고 인터랙티브한 데이터 시각화를 만들 수 있어요.

참고: Vega-Lite의 일부 확장은 Datadog에만 독점적이며, Vega-Lite가 있는 다른 도구로 내보내면 같은 방식으로 동작하지 않을 수 있어요.

테마와 색상 팔레트 커스터마이즈

Datadog은 위젯의 시각적 매력을 높이기 위한 다양한 테마와 색상 팔레트 옵션을 제공해요. 네이티브 Datadog 위젯이 사용하는 스타일 선택과 어울리도록 커스텀 색상을 지정할 수 있어요. 커스텀 색상을 설정하면 앱 테마가 변경될 때 그래프가 색상을 조정하지 않아요. 기본적으로 Datadog 그래프는 다크 모드에서 볼 때 읽기 좋은 대비를 보장하기 위해 텍스트와 축 마크의 색상을 조정해요. 그래프 축에는 커스텀 색상을 설정하지 않는 것이 좋아요.

커스터마이즈된 색상, 글꼴, 간격 및 기타 디자인 설정을 사용할 수 있어요. 이러한 설정은 테마 전환기(CTRL + OPT + D)를 사용할 때 자동으로 적용돼요.

커스텀 색상 팔레트

hex 코드로 커스텀 색상 팔레트를 만들 수도 있지만, Datadog 색상 팔레트를 사용하면 라이트 모드와 다크 모드 사이의 자동 전환이 보장돼요.

Datadog은 공개 Vega 색상 스킴 외에도 추가 색상 팔레트를 제공해요:

dog_classic_area
datadog16
hostmap_blues

추가 리소스:

시각화 단위 커스터마이즈

Datadog은 150개 이상의 단위에 대한 단위 인식 숫자 서식을 제공해서, 3600(초) 같은 값을 1(시간)로 쉽게 서식화할 수 있어요. Vega-Lite 정의에서 이 기능을 사용하려면 JSON 블록의 루트에 "config": {"customFormatTypes": true} 파라미터를 추가하세요.

그다음 format 키를 설정하는 곳 어디에서나 formatType: hoverFormatter를 사용하고 단위를 배열로 정의하세요. 예:

{% collapsible-section %}

커스텀 단위가 있는 Vega-Lite 스펙 예시

{
    "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
    "description": "A simple bar chart with embedded data.",
    "data": {
    "values": [
        {"grade": "A", "total": 28},
        {"grade": "B", "total": 55},
        {"grade": "C", "total": 43}
    ]
    },
    "config": {"customFormatTypes": true},
    "mark": "bar",
    "encoding": {
        "x": {"field": "total", "type": "quantitative"},
        "y": {
            "field": "grade",
            "type": "nominal",
            "axis": {
                "formatType": "hoverFormatter",
                "format": {"units": ["second", null]}
            }
        }
    }
}

{% /collapsible-section %}

"units" 배열의 두 번째 요소는 "bits per second" 같은 "per" 단위를 나타내요. 단위는 단수 형태로 제공해야 해요("seconds" 대신 "second"). 정밀도 지정, 과학적 표기, 정수 같은 일반 숫자 서식은 d3-format 토큰을 사용해 가능해요. 자주 쓰는 두 가지 형식은 다음과 같아요:

~s: 과학적 접두사(예: 2000 -> 2k), 끝에 붙은 0 제거됨
.2f: 소수점 2자리 부동소수점

hoverFormatter는 Vega 표현식에서도 호출할 수 있어요. 이 함수의 시그니처는 다음과 같아요:

# `CanonicalUnitName` refers to any of the strings listed as a Datadog unit.

(
   datum: number,
   params?: {
       units?: [CanonicalUnitName, CanonicalUnitName];
   },
)

추가 리소스:

반응형 크기 조정

위젯은 기본적으로 사용 가능한 공간에 맞게 자동 조정되는 반응형 크기 조정을 사용해요. 하지만 특히 막대 차트 안에서 스크롤을 활성화하고 싶다면 각 데이터 요소에 고정 높이를 설정할 수 있어요. 색상 커스터마이즈와 마찬가지로, 크기 조정을 커스터마이즈하면 자동 반응형 크기 조정이 비활성화돼요.

예를 들어 다음 구성을 사용해 각 요소의 높이 증분을 지정할 수 있어요:

{% collapsible-section %}

커스텀 높이가 있는 Vega-Lite 스펙 예시

{
    "width": 120,
    "height": 120,
    "data": {"url": "data/cars.json"},
    "mark": "bar",
    "encoding": {
        "x": {
            "field": "Name",
            "scale": {"round": false}
        },
        "y": {"aggregate": "count"}
    }
}

{% /collapsible-section %}

Vega-Lite에서 Datadog 데이터 참조하기

Datadog에서 각 "request" 또는 쿼리는 Vega의 명명된 데이터 소스에 대응해요. 이 소스들의 번호는 1부터 시작해요. 즉 위젯이 여러 요청을 하면 table1, table2 등으로 명명된 데이터셋이 생성돼요.

{% image source="https://docs.dd-static.net/images/dashboards/guide/using_vega_lite_in_wildcard_widgets/wildcard_multiple_requests.c1c121e8ef636243e9c9efba4d954a83.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/dashboards/guide/using_vega_lite_in_wildcard_widgets/wildcard_multiple_requests.c1c121e8ef636243e9c9efba4d954a83.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Example wildcard widget with multiple requests" /%}

가능할 때마다 Datadog 위젯은 요청의 "group by" 필드에서 태그 이름을 보존해요. Scalar나 Timeseries 같은 수식과 함수 요청의 경우 "Formula Aliases"가 필드 이름으로 사용돼요. 예시는 Wildcard 위젯 문서를 참고하세요.

추가 필드 정보

Timeseries 요청에는 밀리초 단위 타임스탬프를 위한 _time 필드가 포함돼요.
Histogram 요청 행은 start, end, count 세 필드로 구성돼요.
List 요청 응답은 데이터 소스에 따라 달라져요. DataPreview를 사용해 사용 가능한 필드를 확인하세요.

특수 문자가 있는 필드 이름

영숫자가 아닌 문자를 포함한 필드 이름에는 특별한 고려 사항이 적용돼요. Datadog 메트릭 태그는 대부분의 영숫자 외 문자를 금지해요. 하지만 모든 제품이 이 제약을 갖는 것은 아니며, Vega-Lite에서 이중 의미를 가질 수 있는 문자를 속성 이름에 허용하기도 해요. 이러한 문자에는 객체 모양의 데이터에서 중첩 속성에 접근하는 데 사용되는 대괄호 []와 마침표 .가 포함돼요. 백엔드가 /scalar 및 /timeseries 데이터에서 반환하기 전에 데이터를 평탄화하므로 이들을 이스케이프해야 해요.

이 문자가 와일드카드 위젯에서 올바르게 해석되도록 하려면 \\\\로 이스케이프해야 해요. 예를 들어 RUM 쿼리 필드 @view.name을 사용할 때 Vega-Lite 스펙에서는 @view\\\\.name으로 작성하세요.

지원되는 데이터 형식에 대한 자세한 내용은 Wildcard 위젯 문서를 참고하세요.

컨텍스트 메뉴와 컨텍스트 링크

Datadog 위젯에서는 그래프 데이터포인트를 클릭해 컨텍스트 링크가 있는 그래프 컨텍스트 메뉴를 열 수 있어요. 위젯 구성에 특정 파라미터를 추가하면 와일드카드 위젯에서 이 기능을 활성화할 수 있어요.

컨텍스트 메뉴 기능을 활성화하려면 Vega-Lite 구성에 다음 파라미터를 포함하세요:

"params": [
  {
    "name": "datadogPointSelection",
    "select": "point"
  }
]

그래프에 layer 키가 포함된 경우, 파라미터는 스펙의 루트가 아니라 레이어 객체 중 하나에 추가해야 해요. 루트의 파라미터는 모든 레이어에 적용되어 충돌을 일으킬 수 있기 때문이에요. 이를 피하려면 각 레이어에 datadogPointSelection_ 접두사를 붙여 고유하게 명명된 파라미터를 주세요. 예: datadogPointSelection_squares 또는 datadogPointSelection_circles. 예:

"layer": [
  {
    "mark": "line",
    "encoding": {
      "x": { "field": "_time", "type": "temporal" },
      "y": { "field": "cpu", "type": "quantitative" },
      "color": { "field": "host", "type": "nominal" },
      "opacity": { "value": 0.4 }
    },
    "params": [
      {
        "name": "datadogPointSelection_lines",
        "select": { "type": "point", "on": "click" }
      }
    ]
  },
  {
    "mark": "point",
    "encoding": {
      "x": { "field": "_time", "type": "temporal" },
      "y": { "field": "cpu", "type": "quantitative" },
      "color": { "field": "host", "type": "nominal" },
      "size": { "value": 50 }
    },
    "params": [
      {
        "name": "datadogPointSelection_circles",
        "select": { "type": "point", "on": "click" }
      }
    ]
  }
],

이 기능을 활성화한 후에는 위젯의 데이터포인트를 클릭해 컨텍스트 메뉴를 열 수 있어요. 그래프 편집기의 컨텍스트 링크와 함께 그래프 컨텍스트 메뉴를 사용하세요. 컨텍스트 링크는 대시보드 위젯을 Datadog의 다른 페이지는 물론, 워크플로에 통합한 타사 애플리케이션과도 연결해 줘요. 자세한 내용은 컨텍스트 링크를 참고하세요.

href 인코딩을 통해 동적 커스텀 링크를 추가할 수도 있어요. 선택 항목의 전체 컨텍스트 메뉴가 필요하지 않은 경우에 유용해요.

더 알아보기 (Learn more)

도움이 되는 추가 문서, 링크, 아티클이에요: