Chart Block 設定ガイド¶

Chart Block を使用すると、Markdown ノート内にリアルタイムでレンダリングされるチャートを挿入できます。静的な画像とは異なり、Chart Block ではチャートの種類、クエリ文、表示パラメータを設定するだけで、プレビュー時にプラットフォームのチャートコンポーネントが自動的にクエリを実行し、結果を描画します。

基本的な書き方¶

Markdown 内で fenced code block を使用し、言語タグは必ず chart と指定します。

version: chart/v1
type: sequence
name: サービス P99 レイテンシ
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::`service_latency`:(p99(`duration`)) { service = "checkout" }'
settings:
  chartType: line
  legendPostion: bottom
  isTimeInterval: true
  xAxisShowType: time
  mainMeasurementQueryCode: A
  unitType: custom
  globalUnit:
    - custom
    - ms

対応しているチャートの種類¶

チャート	`type`	説明
時系列折れ線グラフ	`sequence`	時間経過に伴う傾向を表示。メトリクス、ログ件数、レイテンシ、エラー率などに使用
サマリーグラフ	`singlestat`	合計、ピーク値、平均値などの単一の主要数値を表示
テーブルグラフ	`table`	明細または集計後の複数列データを表示
棒グラフ	`bar`	カテゴリ別の比較を表示。ソース別、ステータスコード別、サービス別の集計などに使用
ヒストグラム	`histogram`	分布を表示。処理時間分布、bucket 分布などに使用
円グラフ	`pie`	構成比を表示。エラータイプの比率、ソース別の比率などに使用

共通フィールド¶

フィールド	必須	説明
`version`	はい	固定値 `chart/v1`
`type`	はい	チャートの種類。現在対応している6種類のみ使用可能
`name`	はい	チャートのタイトル。チャートカードのヘッダーに表示
`description`	いいえ	チャートの説明。主に設定の可読性向上のために使用
`time.range`	いいえ	クエリの時間範囲。例：`15m`、`1h`、`1d`。未指定時は `1h` でプレビュー
`queries`	はい	クエリのリスト。空でない配列が必要
`settings`	いいえ	チャートの表示設定。チャートの種類によって異なるフィールドを使用可能

注意

Chart Block の直前の行にある Markdown 見出しが name と完全に一致する場合、プレビュー時に外側の見出しは自動的に非表示となり、見出しの重複表示を防ぎます。

queries フィールド¶

queries は配列で、各クエリ項目が1つのチャートクエリを表します。

フィールド	必須	説明
`code`	はい	クエリ番号。`A`、`B`、`C` の使用を推奨
`qtype`	はい	クエリ言語。`dql`、`promql` に対応
`namespace`	いいえ	クエリの名前空間。DQL でよく使用される値：`metric`、`log`、`object`、`event`、`tracing`、`rum`
`q`	はい	クエリ文
`name`	いいえ	クエリの表示名。未指定時は `code` を使用

q はシングルクォーテーションで囲むことを推奨します。YAML での特殊文字の解析エラーを防ぐためです。

q: 'L::re(`.*`):(count(`*`)) BY `source`'

クエリ文自体にシングルクォーテーションが含まれる場合は、YAML のシングルクォーテーション文字列内で2つのシングルクォーテーションとして記述します。

q: 'L::re(`.*`):(count(`*`)) { `service` = ''checkout'' }'

settings 共通設定¶

settings はプラットフォームの既存チャートコンポーネントにそのまま渡されます。よく使用されるフィールドは以下のとおりです。

フィールド	説明
`chartType`	チャート内部の形状。例：`line`、`areaLine`、`bar`、`pie`、`doughnut`、`histogram`
`legendPostion`	凡例の位置。よく使用される値：`bottom`、`right`、`hide`。フィールド名は `legendPostion` であることに注意
`precision`	小数点以下の精度。文字列で指定することを推奨。例：`"2"`
`isTimeInterval`	時系列で表示するかどうか。時系列グラフでは通常 `true`、グループ化グラフでは通常 `false`
`xAxisShowType`	X軸の表示方法。時系列では `time`、カテゴリでは `groupBy` をよく使用
`mainMeasurementQueryCode`	主クエリ番号。通常は `A` を使用
`mainMeasurementSort`	主指標のソート方法。`top`、`bottom` をよく使用
`mainMeasurementLimit`	表示数の上限。例：`10`、`20`
`unitType`	単位の種類。`custom` をよく使用
`globalUnit`	グローバル単位。例：`['custom', 'ms']`、`['custom', 'count']`
`showLine`	サマリーグラフでトレンドラインを表示するかどうか
`openStack`	積み上げを有効にするかどうか
`stackType`	積み上げの種類
`enableCombine`	円グラフで小さい項目を結合するかどうか
`combine`	円グラフの結合ルール
`promqlType`	PromQL クエリの種類。`rangeQuery` をよく使用

各チャートの例¶

時系列折れ線グラフ sequence¶

ある指標の時間経過に伴う傾向を表示するのに適しています。

version: chart/v1
type: sequence
name: サービス P99 レイテンシ
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::`service_latency`:(p99(`duration`)) { service = "checkout" }'
settings:
  chartType: line
  legendPostion: bottom
  isTimeInterval: true
  xAxisShowType: time
  mainMeasurementQueryCode: A
  unitType: custom
  globalUnit:
    - custom
    - ms

サマリーグラフ singlestat¶

エラー総数、ピーク値、平均値などの単一の主要指標値を表示するのに適しています。

version: chart/v1
type: singlestat
name: 直近1時間のエラー数
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(count(`*`)) { status = "error" }'
settings:
  precision: "0"
  isTimeInterval: false
  showLine: false
  unitType: custom
  globalUnit:
    - custom
    - count

テーブルグラフ table¶

トップリスト、明細リスト、または集計結果の表示に適しています。

version: chart/v1
type: table
name: トップ 遅いインターフェース
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(`time`, `source`, `message`) LIMIT 20'
settings:
  queryMode: toGroupColumn
  showColumns:
    - time
    - source
    - message
  mainMeasurementQueryCode: A
  mainMeasurementSort: top
  mainMeasurementLimit: 20

棒グラフ bar¶

エラーソース分布、ステータスコード分布などのカテゴリ比較を表示するのに適しています。

version: chart/v1
type: bar
name: ログソース分布
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(count(`*`)) BY `source`'
settings:
  direction: vertical
  xAxisShowType: groupBy
  isTimeInterval: false
  showTopSize: false
  aliasVersion: 2
  mainMeasurementLimit: 10
  unitType: custom
  globalUnit:
    - custom
    - count

ヒストグラム histogram¶

分布の表示に適しています。PromQL のシナリオでは bucket/histogram クエリに使用できます。

version: chart/v1
type: histogram
name: リクエスト処理時間分布
time:
  range: 1h
queries:
  - code: A
    qtype: promql
    q: 'histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))'
settings:
  chartType: histogram
  direction: vertical
  legendPostion: bottom
  isTimeInterval: false
  promqlType: rangeQuery
  unitType: custom
  globalUnit:
    - custom
    - ms

円グラフ pie¶

エラータイプの比率、ソース別の比率などの構成比の表示に適しています。

version: chart/v1
type: pie
name: エラーソース比率
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(count(`*`)) { status = "error" } BY `source`'
settings:
  chartType: doughnut
  legendPostion: right
  mainMeasurementQueryCode: A
  mainMeasurementSort: top
  mainMeasurementLimit: 8
  enableCombine: true
  combine:
    percent: "5"
    operator: lt
  unitType: custom
  globalUnit:
    - custom
    - count

フィールド廃止のお知らせ¶

chart/v1 では以下の旧フィールド名は使用しません。新しい設定では対応する代替フィールドを使用してください。

廃止されたフィールド	代替フィールド
`title`	`name`
`view`	`settings`
`queries[].id`	`queries[].code`
`queries[].lang`	`queries[].qtype`
`queries[].datasource`	`queries[].namespace`

誤った例：

version: chart/v1
type: sequence
title: サービスレイテンシ
queries:
  - id: q1
    lang: dql
    datasource: metric
    q: 'M::x'
view:
  chartType: line

正しい例：

version: chart/v1
type: sequence
name: サービスレイテンシ
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::x'
settings:
  chartType: line

設定検証ルール¶

Chart Block はレンダリング前に以下の検証を実行します。

version は chart/v1 である必要があります。
type は sequence、singlestat、table、bar、histogram、pie のいずれかである必要があります。
name は空にできません。
queries は空でない配列である必要があります。
各クエリには code、qtype、q が必須です。
qtype は dql または promql のみ指定可能です。
YAML が正しく解析できる必要があります。

検証に失敗した場合、プレビュー領域にはエラーカードと元の設定内容が表示されます。ノート内の他の Markdown コンテンツの表示には影響しません。

設定の推奨事項¶

Chart Block はクエリと表示パラメータの設定にのみ使用し、data、items、series などの静的なデータを記述しないでください。
クエリ文は、実際に実行可能なクエリを使用し、レンダリング結果の正確性を確保することを推奨します。
複数のチャートを挿入する場合は、複数の chart block を連続して記述し、各 block が1つのチャートに対応します。
テキスト説明のみが必要な場合は、Markdown を直接使用し、Chart Block を使用する必要はありません。
チャートのレンダリング結果が空の場合は、時間範囲、クエリ条件、名前空間、クエリ文を確認することを推奨します。

旧 chart_json 互換性について¶

過去のノートデータとの互換性を維持するため、旧バージョンの chart_json fenced block も引き続き解析可能です。新規ノートおよび AI 生成コンテンツでは、統一して chart/v1 を使用してください。