Chart Block Configuration Guide¶

Chart Block is used to insert real-time rendering charts into Markdown notes. Unlike static images, Chart Block only requires configuration of chart type, query statements, and display parameters. During preview, the platform's chart component automatically executes the queries and renders the results.

Basic Syntax¶

Use a fenced code block in Markdown with the language tag fixed as chart.

version: chart/v1
type: sequence
name: Service P99 Latency
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

Supported Chart Types¶

Chart	`type`	Description
Time Series Line Chart	`sequence`	Shows trends over time, commonly used for metrics, log counts, latency, error rates, etc.
Single Stat Chart	`singlestat`	Displays a core numerical value, suitable for totals, peaks, averages, etc.
Table Chart	`table`	Shows detailed or aggregated multi-column data.
Bar Chart	`bar`	Shows categorical comparisons, e.g., statistics grouped by source, status code, service.
Histogram Chart	`histogram`	Shows distribution, e.g., duration distribution, bucket distribution.
Pie Chart	`pie`	Shows proportions, e.g., error type proportions, source proportions.

Common Fields¶

Field	Required	Description
`version`	Yes	Fixed as `chart/v1`.
`type`	Yes	Chart type, must be one of the 6 currently supported types.
`name`	Yes	Chart title, rendered at the top of the chart card.
`description`	No	Chart description, currently mainly used for configuration readability.
`time.range`	No	Query time range, e.g., `15m`, `1h`, `1d`. Defaults to `1h` for preview if not specified.
`queries`	Yes	Query list, must be a non-empty array.
`settings`	No	Chart display configuration, different chart types can use different fields.

Note

If the Markdown heading on the line immediately preceding the Chart Block exactly matches the name, the external heading will be automatically hidden during preview to avoid duplicate title display.

queries Field¶

queries is an array, each query item represents a chart query.

Field	Required	Description
`code`	Yes	Query identifier, recommended to use `A`, `B`, `C`.
`qtype`	Yes	Query language, supports `dql`, `promql`.
`namespace`	No	Query namespace, common for DQL: `metric`, `log`, `object`, `event`, `tracing`, `rum`.
`q`	Yes	Query statement.
`name`	No	Query display name; uses `code` if not provided.

It is recommended to wrap q in single quotes to avoid YAML parsing issues with special characters.

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

If the query statement itself contains single quotes, they must be written as two single quotes within the YAML single-quoted string.

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

settings Common Configuration¶

settings are passed through to the platform's existing chart component. Common fields are as follows.

Field	Description
`chartType`	Internal chart form, e.g., `line`, `areaLine`, `bar`, `pie`, `doughnut`, `histogram`.
`legendPostion`	Legend position, commonly `bottom`, `right`, `hide`. Note the field name is `legendPostion`.
`precision`	Decimal precision, recommended to write as a string, e.g., `"2"`.
`isTimeInterval`	Whether to display as a time series. Usually `true` for time series charts and `false` for grouped charts.
`xAxisShowType`	X-axis display method, commonly `time` for time series and `groupBy` for categories.
`mainMeasurementQueryCode`	Main query identifier, commonly `A`.
`mainMeasurementSort`	Main metric sorting, commonly `top`, `bottom`.
`mainMeasurementLimit`	Upper limit for displayed items, e.g., `10`, `20`.
`unitType`	Unit type, commonly `custom`.
`globalUnit`	Global unit, e.g., `['custom', 'ms']`, `['custom', 'count']`.
`showLine`	Whether to show a trend line for Single Stat charts.
`openStack`	Whether to enable stacking.
`stackType`	Stacking type.
`enableCombine`	Whether to combine small proportion items for Pie charts.
`combine`	Combination rules for Pie charts.
`promqlType`	PromQL query type, commonly `rangeQuery`.

Examples for Each Chart Type¶

Time Series Line Chart sequence¶

Suitable for showing the trend of a metric over time.

version: chart/v1
type: sequence
name: Service P99 Latency
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

Single Stat Chart singlestat¶

Suitable for displaying a core metric value, such as total errors, peak value, average.

version: chart/v1
type: singlestat
name: Errors in Last Hour
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 Chart table¶

Suitable for displaying Top lists, detail lists, or aggregated results.

version: chart/v1
type: table
name: Top Slow APIs
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 Chart bar¶

Suitable for showing categorical comparisons, e.g., error source distribution, status code distribution.

version: chart/v1
type: bar
name: Log Source Distribution
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 Chart histogram¶

Suitable for showing distribution. In PromQL scenarios, it can be used for bucket/histogram queries.

version: chart/v1
type: histogram
name: Request Duration Distribution
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 Chart pie¶

Suitable for showing proportions, e.g., error type proportions, source proportions.

version: chart/v1
type: pie
name: Error Source Proportion
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

Field Deprecation Notice¶

chart/v1 no longer uses the following old field names. New configurations should use the corresponding replacement fields.

Deprecated Field	Replacement Field
`title`	`name`
`view`	`settings`
`queries[].id`	`queries[].code`
`queries[].lang`	`queries[].qtype`
`queries[].datasource`	`queries[].namespace`

Incorrect example.

version: chart/v1
type: sequence
title: Service Latency
queries:
  - id: q1
    lang: dql
    datasource: metric
    q: 'M::x'
view:
  chartType: line

Correct example.

version: chart/v1
type: sequence
name: Service Latency
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::x'
settings:
  chartType: line

Configuration Validation Rules¶

Chart Block undergoes the following validation before rendering.

version must be chart/v1.
type must be one of sequence, singlestat, table, bar, histogram, pie.
name cannot be empty.
queries must be a non-empty array.
Each query must contain code, qtype, q.
qtype can only be dql or promql.
YAML must be parsable correctly.

If validation fails, the preview area will display an error card and the original configuration content. This does not affect the normal display of other Markdown content in the note.

Configuration Recommendations¶

Chart Block is only for configuring queries and display parameters. Do not write static data within it, such as data, items, series.
Query statements should ideally come from actual executable queries to ensure accurate rendering results.
To insert multiple charts, you can write multiple consecutive chart blocks, each corresponding to one chart.
If only text description is needed, write directly in Markdown; there is no need to use Chart Block.
If the chart renders empty results, it is recommended to first check the time range, query conditions, namespace, and query statement for correctness.

Legacy chart_json Compatibility Notice¶

The system can still parse legacy chart_json fenced blocks to maintain compatibility with historical note data. For new notes and AI-generated content, please uniformly use chart/v1.