vizspec

vizspec 모듈은 ADVN 문서를 생성하고, 검증하고, 파싱하고, 다른 출력 형식으로 변환하는 JSH API입니다. ADVN은 Analysis Data Visualization Notation의 약자로, 분석 결과 시각화를 위한 renderer-중립 문서 형식입니다.

ADVN을 사용하면 데이터의 의미와 renderer-specific 출력을 분리할 수 있습니다.

ADVN과 vizspec

• ADVN은 의미 중심의 semantic layer 입니다.
• ADVN은 문서 형식입니다. 분석 결과가 무엇을 의미하는지 표현합니다.
• vizspec 모듈은 ADVN 문서를 생성하고 변환하는 JSH API입니다.
• viz는 ADVN 문서를 검증하고 미리 보고 내보내는 명령어입니다.

기본 예제

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

const vizspec = require('vizspec');

const spec = new vizspec.Builder()
    .setDomain({
        kind: 'time',
        timeformat: vizspec.Timeformat.ns,
    })
    .setXAxis({ id: 'time', type: 'time', label: 'Time' })
    .addYAxis({ id: 'value', type: 'linear', label: 'Value' })
    .addTimeBucketValueSeries({
        id: 'series-1',
        axis: 'value',
        data: [
            ['1712102400000000000', 10],
            ['1712102460000000000', 12],
        ],
    })
    .build();

상수

모듈은 다음 상수 그룹을 제공합니다.

• RepresentationKind
• AnnotationKind
• Timeformat

애플리케이션 코드에서 ADVN 값을 명시적으로 지정할 때 이 상수들을 사용하면 오타를 줄일 수 있습니다.

RepresentationKind

AnnotationKind

Timeformat

parse()

ADVN JSON 문자열을 파싱해서 정규화된 spec object 를 반환합니다.

사용 형식

parse(text)

파라미터

사용 예시

1
2
3

const vizspec = require('vizspec');
const spec = vizspec.parse('{"version":1,"series":[]}');
console.println(spec.version);

stringify()

spec object 를 ADVN JSON 문자열로 직렬화합니다.

사용 형식

stringify(spec)

파라미터

사용 예시

1
2
3

const vizspec = require('vizspec');
const text = vizspec.stringify(vizspec.createSpec({ version: 1 }));
console.println(typeof text);

validate()

spec object 를 검증합니다. 구조나 필드 조합이 잘못되면 예외를 발생시킵니다.

사용 형식

validate(spec)

파라미터

사용 예시

1
2
3

const vizspec = require('vizspec');
const ok = vizspec.validate(vizspec.createSpec({ version: 1 }));
console.println(ok);

normalize()

부분적으로 작성된 spec object 를 정규화하고 기본 구조 필드를 채웁니다.

사용 형식

normalize(spec)

파라미터

사용 예시

1
2
3

const vizspec = require('vizspec');
const spec = vizspec.normalize({});
console.println(spec.version);

createSpec()

initializer 로부터 spec object 를 생성하고, 정규화하고, 검증합니다.

사용 형식

createSpec(init)

파라미터

사용 예시

1
2
3
4
5
6

const vizspec = require('vizspec');
const spec = vizspec.createSpec({
    domain: { kind: 'time', timeformat: vizspec.Timeformat.ns },
    series: [],
});
console.println(spec.domain.kind);

listSeries()

spec.series 의 정규화된 요약 목록을 반환합니다.

사용 형식

listSeries(spec)

파라미터

반환 필드

사용 예시

1
2
3

const listed = vizspec.listSeries(spec);
console.println(listed[0].id);
console.println(listed[0].tuiLinesCompatible);

Series helper

Series helper 함수는 올바른 representation kind 와 기본 field 구성을 가진 series object 를 만듭니다.

사용 가능한 helper:

• rawPointSeries(init)
• timeBucketValueSeries(init)
• timeBucketBandSeries(init)
• distributionHistogramSeries(init)
• distributionBoxplotSeries(init)
• eventPointSeries(init)
• eventRangeSeries(init)

사용 형식

timeBucketValueSeries(init)
eventRangeSeries(init)

공통 initializer 필드

사용 예시

1
2
3
4
5
6
7

const vizspec = require('vizspec');
const series = vizspec.timeBucketValueSeries({
    id: 'cpu',
    axis: 'value',
    data: [['1712102400000000000', 10]],
});
console.println(series.representation.kind);

Annotation helper

Annotation helper 함수는 올바른 annotation kind 를 가진 top-level annotation object 를 만듭니다.

사용 가능한 helper:

• pointAnnotation(init)
• lineAnnotation(init)
• rangeAnnotation(init)

사용 형식

lineAnnotation(init)
rangeAnnotation(init)

공통 initializer 필드

사용 예시

1
2
3

const vizspec = require('vizspec');
const annotation = vizspec.lineAnnotation({ axis: 'value', value: 80, label: 'warning' });
console.println(annotation.kind);

Builder

fluent style 로 ADVN 문서를 만들고 싶다면 builder 를 사용하십시오.

사용 형식

new Builder([init])

주요 메서드

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

const vizspec = require('vizspec');

const spec = new vizspec.Builder()
    .setDomain({ kind: 'time', timeformat: vizspec.Timeformat.ns })
    .setXAxis({ id: 'time', type: 'time', label: 'Time' })
    .addYAxis({ id: 'value', type: 'linear', label: 'Temperature' })
    .addTimeBucketBandSeries({
        id: 'sensor-1',
        axis: 'value',
        data: [
            ['1712102400000000000', 18, 24, 21],
            ['1712102460000000000', 17, 23, 20],
        ],
    })
    .build();

Output adapter

toEChartsOption()

spec 을 ECharts option object 로 변환합니다.

사용 형식

toEChartsOption(spec[, options])

파라미터

옵션 필드

사용 예시

1
2
3
4
5

const option = vizspec.toEChartsOption(spec, {
    timeformat: vizspec.Timeformat.rfc3339,
    tz: 'Asia/Seoul',
});
console.println(JSON.stringify(option));

toTUILines()

첫 번째 sparkline-compatible series 를 terminal 친화적인 sparkline line 배열로 변환합니다.

사용 형식

toTUILines(spec[, options])

파라미터

옵션 필드

참고:

• seriesId 를 주지 않으면 toTUILines() 는 첫 번째 sparkline-compatible series 를 반환합니다.
• seriesId 를 주면 해당 series[].id 와 일치하는 series 를 렌더링합니다.
• 선택 가능한 series id 를 미리 확인하려면 listSeries() 를 사용하십시오.
• seriesId 가 없거나 sparkline-compatible 하지 않은 series 를 가리키면 오류가 발생합니다.
• 반환 값은 multi-line TUI chart 를 구성하는 terminal 친화적인 line 배열입니다.
• toTUIBlocks() 와 달리 axis label 을 포함한 확장된 multi-line chart 형태를 유지합니다.
• height 는 raw-point, time-bucket-value 출력에만 적용됩니다. time-bucket-band 는 기존 max/avg/min 형식을 유지합니다.
• toTUILines() 는 현재 rows, compact option 을 받아도 사용하지 않습니다.

사용 예시

1
2

const lines = vizspec.toTUILines(spec, { width: 32, height: 5, seriesId: 'series-1' });
console.println(lines.join('\n'));

CLI 예시:

viz lines --height 5 --series series-1 sample.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

const vizspec = require('vizspec');
const { Client } = require('machcli');

const dbConf = {
    host: '127.0.0.1', port: 5656,
    user: 'sys', password: 'manager',
};

var db, conn, rows;
var data = [];
try {
    db = new Client(dbConf);
    conn = db.connect();
    rows = conn.query(`SELECT TIME, VALUE FROM EXAMPLE
        WHERE NAME = ? AND TIME > now - 2h`, 'machbase:ps:cpu_percent');
    for (const row of rows) {
        data.push([row.TIME, row.VALUE]);
    }
} catch( e ) {
    console.println("ERROR", e.message);
} finally {
    rows && rows.close();
    conn && conn.close();
    db && db.close();
}

const spec = new vizspec.Builder()
    .setDomain({ kind: 'time', timeformat: vizspec.Timeformat.rfc3339 })
    .setXAxis({ id: 'time', type: 'time', label: 'Time' })
    .addYAxis({ id: 'value', type: 'linear', label: 'Value' })
    .addTimeBucketValueSeries({ id: 'series-1', axis: 'value', data: data })
    .build();

console.println(vizspec.toTUILines(spec, { width: 80 }).join('\n'));

출력 예:

toTUIBlocks()

spec 을 terminal inspection 용 TUI block object 배열로 변환합니다.

사용 형식

toTUIBlocks(spec[, options])

파라미터

옵션 필드

반환 값

반환 값은 block object 배열입니다. 각 block 은 공통적으로 다음 필드를 가질 수 있습니다.

type 에 따라 실제로 채워지는 필드는 다를 수 있습니다. 예를 들어 sparkline block 은 주로 lines 를 사용하고, table block 은 columns, rows, meta 를 사용합니다.

참고:

• toTUIBlocks() 의 sparkline block 은 원래의 compact sparkline 표현을 반환합니다.
• axis label 과 여러 chart row 를 포함한 확장 형태가 필요하면 toTUILines() 를 사용하십시오.

사용 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

const blocks = vizspec.toTUIBlocks(spec, {
    width: 80,
    rows: 5,
    timeformat: vizspec.Timeformat.rfc3339,
    tz: 'Asia/Seoul',
});
console.println(blocks[0].type);           // summary
console.println(blocks[0].stats[0].label); // series
console.println(blocks[2].type);           // sparkline
console.println(blocks[2].lines[0]);       // ▁▃▅▇█▆▄▂

toSVG()

spec 을 SVG 문자열로 변환합니다.

사용 형식

toSVG(spec[, options])

파라미터

옵션 필드

사용 예시

1
2
3
4
5
6
7

const svg = vizspec.toSVG(spec, {
    title: 'Sensor Overview',
    width: 960,
    height: 420,
    timeformat: vizspec.Timeformat.rfc3339,
    tz: 'Asia/Seoul',
});

toPNG()

spec 을 PNG binary data 로 변환합니다. 반환 값은 ArrayBuffer 이며, 필요하면 new Uint8Array(png) 로 읽을 수 있습니다.

사용 형식

toPNG(spec[, options])

파라미터

옵션 필드

레이아웃 및 텍스트 필드:

rasterization 필드:

참고:

• scale 과 dpi 를 함께 주면 scale 이 우선합니다.
• 현재 PNG renderer 는 MRTG 스타일 output 을 생성합니다.
• JavaScript API 는 단일 options object 를 받아 내부적으로 layout 필드와 rasterization 필드로 분리합니다.
• 하위 호환을 위해 기존 toPNG(spec, svgOptions, pngOptions) 호출 형태도 계속 지원합니다.

사용 예시

1
2
3
4
5
6
7
8
9

const png = vizspec.toPNG(spec, {
    title: 'Sensor Overview',
    width: 640,
    height: 240,
    scale: 2,
    theme: 'mrtg'
});
const bytes = new Uint8Array(png);
console.println(bytes[0].toString(16));

시간 처리

epoch timestamp 를 s, ms, us, ns 형식으로 사용하면 값 자체가 UTC 기준 절대 시간을 나타내므로 입력 데이터에 timezone 을 따로 명시할 필요가 없습니다. timezone 은 원본 timestamp 에 붙이는 정보라기보다, 그 timestamp 를 사람이 읽는 문자열로 렌더링할 때 적용하는 출력 옵션으로 이해하면 됩니다.

특히 ns 는 값의 자릿수가 커서 JavaScript number 로 표현하면 정밀도가 손실될 수 있습니다. 예를 들어 1712102400000000000 같은 값은 IEEE 754 배정밀도 부동소수점의 안전한 정수 범위를 넘기므로, nanosecond epoch 는 문자열로 전달하는 것을 권장합니다.

Machbase Neo timestamp 데이터에는 다음 조합을 권장합니다.

• timeformat: vizspec.Timeformat.ns
• JavaScript number 대신 문자열 timestamp 사용

예시:

const spec = vizspec.createSpec({
    domain: {
        kind: 'time',
        timeformat: vizspec.Timeformat.ns,
    },
    series: [vizspec.eventRangeSeries({
        id: 'maintenance',
        data: [['1712102400000000000', '1712102460000000000', 'maintenance']],
    })],
});

시간 렌더링

데이터 소스의 시간 인코딩과 출력 시점의 시간 표현은 서로 다른 관심사입니다.

• domain.timeformat 은 ADVN 문서 안의 timestamp 인코딩을 설명합니다.
• adapter option 의 timeformat, tz 는 그 timestamp 를 어떤 형식과 timezone 으로 렌더링할지 설명합니다.

adapter option 을 생략하면 vizspec adapter 는 기본적으로 rfc3339 와 local timezone 을 사용합니다.

예시:

const svg = vizspec.toSVG(spec, {
    title: 'CPU Usage',
    width: 960,
    height: 420,
    timeformat: vizspec.Timeformat.rfc3339,
    tz: 'Asia/Seoul',
});

같은 규칙이 toTUIBlocks() 와 toEChartsOption() 에도 적용됩니다.

viz 명령어 사용

생성한 스펙을 검증하려면 다음과 같이 실행합니다.

/work > viz validate cpu-usage.json
VALID version=1 series=1 annotations=1

터미널에서 확인하려면 다음과 같이 실행합니다.

/work > viz view cpu-usage.json

SVG 로 내보내려면 다음과 같이 실행합니다.

/work > viz export --title "CPU Usage" --output cpu-usage.svg cpu-usage.json

출력 시간 형식과 timezone 을 명시하려면 다음과 같이 실행합니다.

/work > viz view --timeformat rfc3339 --tz Asia/Seoul cpu-usage.json