custom-visualization-builder

カスタム可視化ビルダー

@splunk/dashboard-studio-extension フレームワークを使用して、カスタム Splunk ダッシュボード可視化を作成し、ビルド、パッケージ化、インストールします。可視化はサンドボックス化された iframe 内で実行され、Splunk の検索からデータを受け取ります。プレーンな JavaScript または React で構築できます。必要な可視化に応じて選択してください。

開発にローカルの Splunk インスタンスは必要ありません。ローカルでビルドとパッケージ化を行い、対応するインスタンスに .spl をインストールします。Splunk Enterprise 10.4+ または Splunk Cloud Platform（同等のリリース）が必要です。

使用するタイミング

ユーザーから Splunk の新しいカスタム可視化の作成、既存の dashboard-studio-extension プロジェクトへの可視化の追加、可視化の Splunk アプリとしてのパッケージ化、または従来の RequireJS カスタム可視化から現在の拡張フレームワークへの移行を依頼された場合に、このスキルを使用します。

ユーザーが対象を明示的に確認しない限り、本番環境または共有 Splunk 環境に可視化をインストールまたは更新しないでください。ユーザーに認証情報をそのまま尋ねないでください。すでに設定されているローカル Splunk 認証を使用するか、ユーザーがインストールコマンドを実行するようにしてください。

---

前提条件

• Node.js >= 22
• Yarn >= 1.22
• 対象インスタンス：Splunk Enterprise 10.4+ または Splunk Cloud Platform（同等のリリース）

---

フレームワークを選ぶ

	JavaScript (@splunk/dashboard-studio-extension)	React (@splunk/dashboard-studio-extension/react)
使用する場面	Canvas の描画、D3、プレーンな DOM、依存関係を最小限にしたい場合	コンポーネント中心の UI、フックベースの状態管理、新規プロジェクトの大半
API の形式	イベントリスナー + ゲッター	フック（useDataSources、useDimensions、useOptions、…）
エントリーファイル	visualization.js	visualization.jsx
追加の依存関係	なし	react、react-dom（ピア依存関係、スキャフォールドで追加）

---

プロジェクト構成

プロジェクトは Splunk アプリであり、visualizations/ の下に 1 つ以上の可視化を含めることができます。各可視化は、config.json、src/、SPL.md を含む独自のディレクトリを持ちます。

my-viz-project/
├── package.json
├── build.mjs                    # esbuild orchestrator
├── build-plugins/
│   └── css-and-size.mjs         # CSS injection + asset inlining plugin
├── package.mjs                  # .spl packager
├── package/
│   └── app/
│       └── app.conf             # Splunk app identity (source of truth for id/version)
├── visualizations/
│   ├── <viz-one>/
│   │   ├── SPL.md               # SPL reference for this viz (you create this)
│   │   ├── config.json
│   │   └── src/
│   │       ├── visualization.js(x)
│   │       └── visualization.css
│   └── <viz-two>/
│       ├── SPL.md
│       ├── config.json
│       └── src/
│           ├── visualization.js(x)
│           └── visualization.css
└── dist/                        # build output (generated)

ビルドシステムは visualizations/ の下にあるすべてのディレクトリを自動的に検出し、すべてビルドします。プロジェクトフォルダーには単一の可視化名ではなく、コレクション名を付けてください（例：gauge ではなく splunk-custom-vizzes）。

---

ワークフローの概要

1. 要件を確認する

コードを生成する前に、ユーザーに質問する（またはコンテキストから確認する）内容：

1. プロジェクト名 — Splunk アプリ ID として使用します。使用できるのは英字、数字、ドット、アンダースコアのみです。ドットまたはアンダースコアで始めたり終えたりすることはできません。例：my_custom_viz。
2. 可視化スラッグ — visualizations/ の下に作成するディレクトリ名です。使用できるのは小文字、数字、アンダースコア（[a-z0-9_]）のみです。ドット、スラッシュ、スペースは使用できません。ファイルが visualizations/<viz-slug>/ の外に配置される値は拒否してください。例：network_graph。
3. 可視化の表示ラベル — Splunk UI に表示される、人が読める名前です。例：「Network Graph」。
4. 説明 — 可視化の機能を説明する 1 行の文です。
5. 作成者 — app.conf 用です。
6. 想定される SPL 列 — 検索で生成する必要があるフィールドです。必須と任意を区別してください。
7. 設定可能な項目 — ユーザーが調整できるようにする項目（色、しきい値、切り替えなど）です。それぞれについて、名前、型、デフォルト値を確認してください。
8. 描画方法 — フレームワークの選択に役立つ、描画またはレンダリングするもの（Canvas の図形、チャート、テーブル、マップなど）です。

ユーザーの依頼またはコンテキストから明らかに該当しないと判断できる場合を除き、アクセシビリティと安全なレンダリングのデフォルトを適用してください。

ユーザーの依頼が曖昧な場合は、スキャフォールドを作成する前に質問してください。

2. プロジェクトの場所を決める

指定がない場合は、プロジェクトを作成する場所をユーザーに尋ねてください。既存の dashboard-enterprise リポジトリがなくても、空のディレクトリならどこでも構いません。

既存プロジェクトに可視化を追加する場合：ビルド環境を備えたプロジェクトがすでにある場合は、ステップ 3 を完全に省略してください。config.json、src/visualization.js(x)、src/visualization.css、SPL.md を含む visualizations/<viz-name>/ を作成するだけです。ビルド時にすべての可視化ディレクトリが自動検出されるため、登録は不要です。その後、ステップ 5 に進んでください。

3. プロジェクトをスキャフォールドする

現在、@splunk/create CLI では、ラベル、説明、作成者、テンプレートについて対話形式のプロンプトに回答する必要があります。位置引数として渡せるのはプロジェクト名のみです。完全な非対話形式への対応は今後予定されています。ユーザーにコマンドを実行し、残りのプロンプトに回答してもらってください。

「ターミナルで次のコマンドを実行して、プロンプトに回答してください。完了したらお知らせください。」

mkdir <project-name> && cd <project-name>
npx @splunk/create@latest --mode=dashboard-studio-extension <app_id>

プロンプトが表示されたら、次の値を使用してください。

• 表示ラベル：<Human Readable Label>
• 説明：<description>
• 作成者：<author>
• テンプレート：上記で選択したフレームワークに応じて JavaScript または React

その後、yarn を実行して依存関係をインストールします。

スキャフォールドの作成が完了したことをユーザーが確認するまで、次に進まないでください。

スキャフォールドの作成後、package/app/app.conf に正しいアプリの識別情報が設定されていることを確認します。 スキャフォールドでは、プロンプトへの回答を値に反映した次の形式が生成されます。

[package]
id = <app_id>

[id]
version = 0.1.0
name = <app_id>

[ui]
is_visible = 1
label = <Human Readable Label>
show_in_nav = 0

[launcher]
author = <author>
description = <description>
version = 0.1.0

[install]
is_configured = 0
build = <@- buildNumber @>
check_for_updates = 0

[manifest]
category = Custom

アプリの id に使用できるのは、英字、数字、ドット、アンダースコアのみです。ドットまたはアンダースコアで始めたり、終えたりすることはできません。

build = <@- buildNumber @> はそのままにしてください。 このテンプレートタグには意図があります。パッケージャー（yarn package）がアプリをステージングする際に、実際のビルド番号に置き換えます。 リテラル値に置き換えないでください。

次に、viz ディレクトリ内に SPL.md を作成します（visualizations/<viz-name>/SPL.md）。

# <Display Label> — SPL Reference

## Expected Columns

| Column | Type | Required? | Description |
|--------|------|-----------|-------------|
| <col>  | <type> | Yes/Optional | <what it is> |

## Notes

- Key data assumptions, units, fallback behavior, etc.

## Full SPL

\`\`\`spl
<full working SPL query>
\`\`\`

## Time range

`rt-1m` to `rt` (or `-60m` to `now` for historical)

4. ビジュアライゼーションを作成する

visualizations/<viz-name>/config.json — optionsSchema と editorConfig を含む全フィールドのリファレンスについては、references/config-json.md を参照してください。

{
  "showTitleAndDescription": true,
  "includeInToolbar": true,
  "includeInVizSwitcher": true,
  "showDrilldown": false,
  "canSetTokens": [],
  "hasEventHandlers": false,
  "config": {
    "name": "<Human Readable Name>",
    "description": "<description>",
    "category": "Custom",
    "icon": null,
    "dataContract": {
      "requiredDataSources": ["primary"],
      "optionalDataSources": []
    },
    "size": { "initialWidth": 600, "initialHeight": 500 },
    "optionsSchema": {},
    "editorConfig": []
  }
}

---

JavaScript — visualization.js：

データは常に列指向の形式で渡されます：{ fields: [{name}, ...], columns: [[col0val0, col0val1, ...], ...] }。すべての値は文字列です。数値は明示的に解析してください。リスナーメソッドはクリーンアップ関数を返します。

import { VisualizationAPI } from '@splunk/dashboard-studio-extension';
import './visualization.css';

const container = document.createElement('div');
container.className = 'viz-container';
document.body.appendChild(container);

const state = { data: null, loading: false, options: {}, width: 0, height: 0, theme: 'light' };

function render() {
    if (state.loading) { container.innerHTML = '<div class="loading">Loading...</div>'; return; }
    if (!state.data)   { container.innerHTML = '<div class="empty">No data</div>'; return; }

    const { fields, columns } = state.data;
    if (!columns?.length || !columns[0].length) {
        container.innerHTML = '<div class="empty">No data</div>';
        return;
    }

    // Always provide fallbacks — options may be unset even if optionsSchema declares defaults
    const myOption = state.options.myOption ?? 'default';
    const isDark = state.theme === 'dark';

    // implement visualization here
}

VisualizationAPI.addDataSourcesListener(
    ({ dataSources, loading }) => {
        state.loading = loading;
        state.data = dataSources?.primary?.data ?? null;
        render();
    },
    { invokeImmediately: true }
);

VisualizationAPI.addOptionsListener(({ options }) => {
    state.options = options;
    render();
});

VisualizationAPI.addDimensionsListener(({ width, height }) => {
    state.width = width;
    state.height = height;
    render();
}, { invokeImmediately: true });

VisualizationAPI.addThemeListener(({ theme }) => {
    state.theme = theme;
    render();
}, { invokeImmediately: true });

---

React — visualization.jsx：

フックはコンポーネントから直接呼び出してください。

import {
    useDataSources,
    useDimensions,
    useOptions,
    useTheme,
} from '@splunk/dashboard-studio-extension/react';
import { createRoot } from 'react-dom/client';
import './visualization.css';

function Viz() {
    const { dataSources, loading } = useDataSources();
    const { width, height } = useDimensions();
    const { options } = useOptions();
    const { theme } = useTheme();

    // Always provide fallbacks — options may be unset even if optionsSchema declares defaults
    const myOption = options?.myOption ?? 'default';
    const isDark = theme === 'dark';

    if (loading) return <div className="loading">Loading...</div>;

    const data = dataSources?.primary?.data;
    if (!data?.columns?.length || !data.columns[0].length)
        return <div className="empty">No data</div>;

    const { fields, columns } = data;

    // implement visualization here
    return <div style={{ width, height }} />;
}

createRoot(document.getElementById('root')).render(<Viz />);

---

5. 開発する

# Watch mode — rebuilds on file changes
yarn dev

dist/<viz-name>/visualization.js が作成されていることを確認します。変更を確認するには、ブラウザーを強制再読み込みしてください。

6. 本番用にビルドする

yarn build:prod

7. パッケージ化する

yarn package

出力：dist/<app-id>-<version>-<hash>.spl

パッケージャーは、dist/ 内で見つかったビジュアライゼーションから、default/visualizations.conf（framework_type = studio_visualization を含む）と metadata/default.meta を自動生成します。

8. Splunk にインストールする

Splunk Enterprise（10.4 以降）：アプリ > アプリの管理 > ファイルからアプリをインストール → .spl を選択します。再起動は不要です。アプリはすぐに読み込まれます。

Splunk Cloud Platform：プライベートアプリのインストールには、ACS CLI と AppInspect による審査が必要です。プライベートアプリには機能しないため、Cloud ユーザーに Splunk Web のインストール UI を案内しないでください。プライベートアプリの提出手順については、Splunk ACS のドキュメントを案内してください。

ローカル Docker：.spl をコンテナにコピーしてから、すでに構成済みのローカルテストインスタンスに REST 経由でインストールするには、splunkctl を優先して使用してください。

docker cp dist/<app-id>-<version>-<hash>.spl <container>:/tmp/app.spl
splunkctl --yes app install /tmp/app.spl --update 1 --output json

Splunkctl v0.1.0 では、このインストール POST に --yes が必要です。ユーザーが、対象のローカルインスタンス、パッケージ、更新時の動作、および本番以外の範囲を限定したインストールについて明示的に承認した後にのみ使用してください。この承認は、本番環境または共有環境へのインストールを許可するものではありません。

splunkctl が利用できない場合は、その旨を伝え、同じ本番以外の対象とインストール範囲を維持できる場合に限り、顧客が明示的に承認した、顧客指定の既存のローカルインストール方法を使用してください。クライアントを黙ってインストールまたは構成してはならず、本番環境または共有環境へのインストールには、別途明示的な承認を得てください。

9. ユーザーに伝える

• Splunk アプリ ID
• ダッシュボード JSON 用の Viz タイプ文字列：<app-id>.<viz-name>
• データを接続するための SPL クエリの例

Viz を完成として報告する前に、以下を確認してください（依頼内容に該当しない項目は除きます）。

• 信頼できない検索値を DOM に書き込む前にエスケープしている
• インタラクティブ要素にキーボードでアクセスでき、アクセシブルなラベルが付いている
• テキストとアイコンの色が、ライトテーマとダークテーマの両方で背景に対して WCAG AA のコントラスト比を満たしている
• アニメーションが prefers-reduced-motion に従っている

---

例

キャンバス Viz をゼロから新規作成する場合：

「ホスト間の接続を表示するネットワークグラフの可視化を作成してください。」

スキルは要件を収集し、ユーザーにスキャフォールドを作成するよう依頼します。その後、キャンバス描画を使って visualization.js を作成し、データ／ディメンション／テーマのリスナーを接続して、.spl をパッケージ化します。

既存プロジェクトに Viz を追加する場合：

「既存のカスタム Viz プロジェクトにゲージ Viz を追加してください。」

スキルはスキャフォールドの作成を省略し、config.json、src/visualization.js、SPL.md を含む visualizations/gauge/ を作成して、再ビルドするようユーザーに指示します。

レガシー Viz を移行する場合：

「RequireJS のカスタム Viz を新しいフレームワークに移行してください。」

スキルは既存の Viz を読み込み、updateView を render() に対応付け、SplunkVisualizationBase を VisualizationAPI リスナーに置き換え、RequireJS ラッパーを削除して、プロジェクトを再スキャフォールドします。

---

Viz の更新（高速な反復）

可視化コードのみを変更する場合は、ビルド済み JS を直接コピーします。再インストールは不要です。

yarn dev  # or yarn build:prod

cp dist/<viz-name>/visualization.js \
   $SPLUNK_HOME/etc/apps/<app-id>/appserver/static/visualizations/<viz-name>/visualization.js

ブラウザーをハードリフレッシュしてください。Splunk の再起動は不要です。

app.conf、config.json の変更や、新しい Viz の追加には、完全な再インストールを行ってください（手順 7～8）。

showDrilldown の有効化には再起動が必要です：インストール済みのアプリで showDrilldown: true を有効にした後は、Splunk を再起動する必要があります。REST レイヤーは起動時に config.json をキャッシュするため、再インストールだけでは Interactions パネルは更新されません。

---

テーマのサポート

Viz は Splunk のライト／ダークテーマに対応する必要があります。iframe はサンドボックス化されているため、ホストページの CSS カスタムプロパティは継承されません。ハードコードされたエンタープライズテーマの値を使用してください。

JavaScript：

const THEME_COLORS = {
    light: { background: '#ffffff', text: '#1a1a1a', accent: '#4e9cf5' },
    dark:  { background: '#1a1c21', text: '#c3cbd4', accent: '#4e9cf5' },
};

VisualizationAPI.addThemeListener(({ theme }) => {
    state.theme = theme;
    render();
}, { invokeImmediately: true });

function render() {
    const colors = THEME_COLORS[state.theme] ?? THEME_COLORS.light;
    container.style.background = colors.background;
    // use colors.text, colors.accent in drawing logic
}

React：

const THEME_COLORS = {
    light: { background: '#ffffff', text: '#1a1a1a', accent: '#4e9cf5' },
    dark:  { background: '#1a1c21', text: '#c3cbd4', accent: '#4e9cf5' },
};

function Viz() {
    const { theme } = useTheme();
    const colors = THEME_COLORS[theme] ?? THEME_COLORS.light;
    return <div style={{ background: colors.background, color: colors.text }}>...</div>;
}

---

アクセシビリティと安全なレンダリング

以下はデフォルトのルールです。ユーザーの依頼や状況から明らかに該当しない場合を除き、適用してください。

信頼できない検索値を DOM に書き込む前にエスケープしてください。 dataSources の生のフィールド値に対して、innerHTML や insertAdjacentHTML を決して使用しないでください。代わりに textContent、createElement、またはサニタイズヘルパーを使用してください。

// safe
const el = document.createElement('div');
el.textContent = row.label;

// unsafe — do not do this
container.innerHTML = `<div>${row.label}</div>`;

インタラクティブ要素にキーボードでアクセスできるようにしてください。 クリックまたはホバーで動作が発生する場合は、要素に tabIndex="0" を設定し、Enter／Space キーの keydown を処理してください。

el.setAttribute('tabindex', '0');
el.setAttribute('role', 'button');
el.addEventListener('keydown', (e) => {
    if (e.key === 'Enter' || e.key === ' ') handleClick();
});

テキストによる代替情報を用意してください。 キャンバス要素とアイコンのみのコントロールには、アクセシブルなラベルが必要です。

canvas.setAttribute('role', 'img');
canvas.setAttribute('aria-label', 'Network graph showing host connections');

WCAG AA のコントラスト比を満たしてください。 前景のテキストとアイコンは、背景に対して少なくとも 4.5:1 のコントラスト比が必要です（大きなテキストの場合は 3:1）。テーマのサポートにあるハードコードされた THEME_COLORS の値は、デフォルトのテキストについてこの基準をすでに満たしています。これらを基準として使用し、カスタムのアクセントカラーやステータスカラーも確認してください。

prefers-reduced-motion に従ってください。 Viz でアニメーションを使用する場合は、メディアクエリを確認し、設定されている場合は動きを省略するか最小限に抑えてください。

const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
if (!reduceMotion) requestAnimationFrame(animate);

---

Canvas

サイズ設定、インタラクティビティ、ドリルダウンのパターンについては、references/canvas.md を参照してください。

---

スキャフォールドされたビルドでエントリーファイルが選択される仕組み

スキャフォールドされた build.mjs は、各ビジュアライゼーションの拡張子を自動検出しません。すべての package.json スクリプトでグローバルな --entry=<filename> を1つ指定し、ビルドでは visualizations/ 以下のすべてのディレクトリに、そのファイル名を適用します。

const entryArg = process.argv.find((a) => a.startsWith('--entry='));
const entryFileName = entryArg ? entryArg.split('=')[1] : 'visualization.js';
// for each viz: build visualizations/<viz>/src/<entryFileName>
// if that file is missing: "Warning: <viz>/src/<entryFileName> not found, skipping"

jsx: 'automatic' が有効になるのは、entryFileName が .jsx で終わる場合のみです。

考慮すべき点：

• 1つのスキャフォールドされたプロジェクト内のすべてのビジュアライゼーションで、拡張子が共通になります。 JavaScript でスキャフォールドされた プロジェクト（--entry=visualization.js）では visualization.js ファイルのみがビルドされ、React でスキャフォールドされたプロジェクト（--entry=visualization.jsx）では visualization.jsx ファイルのみがビルドされます。
• 拡張子が一致しないファイルは、警告が表示されるだけで静かにスキップされ、終了コードは0になります。 そのため、明らかなエラーがないままビジュアライゼーションが dist/ から消えることがあります。ビジュアライゼーションが dist/ に見当たらない場合は、そのエントリーファイルの拡張子がプロジェクトの --entry と一致しているか確認してください。

React ビジュアライゼーションの追加

• React でスキャフォールドされたプロジェクト： visualizations/<viz>/src/visualization.jsx を追加するだけで、自動的にビルドされます。

• JavaScript でスキャフォールドされたプロジェクトで、残す価値のある JavaScript ビジュアライゼーションがない場合： プロジェクト全体を .jsx に切り替えるのが最も簡単です。React を追加し（yarn add react react-dom）、既存のエントリーファイルの名前を visualization.jsx に変更し、package.json 内のすべての --entry=visualization.js を --entry=visualization.jsx に変更します。jsx: 'automatic' は自動的に有効になります。

• 1つのプロジェクトで .js と .jsx の両方のビジュアライゼーションが本当に必要な場合： スキャフォールドされた単一の --entry によるビルドでは対応できません。build.mjs のエントリーファイル検索処理を、ビジュアライゼーションごとの解決処理（.jsx を優先し、なければ .js を使用）に置き換え、常に jsx: 'automatic' を設定してください。

  const buildOptions = { jsx: 'automatic', /* ... */ };
  
  function resolveEntry(vizName) {
      for (const name of ['visualization.jsx', 'visualization.js']) {
          const p = join(visualizationsDir, vizName, 'src', name);
          if (existsSync(p)) return p;
      }
      return null;
  }
  

  その後、package.json のスクリプトから --entry フラグを削除します。（これはローカルでの 変更であり、@splunk/create が生成する内容ではありません。）

エントリーファイルでは @splunk/react-ui を使用しないでください。 スキャフォールドされた React テンプレートのデフォルトの ビジュアライゼーションは @splunk/react-ui のコンポーネント（Table、Paragraph、WaitSpinner）をインポートしますが、これらは CommonJS として事前バンドルされており、デフォルトエクスポートはスキャフォールドの esbuild ESM パイプラインを通過できません。そのため、ビルドされたビジュアライゼーションは読み込み時に Minified React error #130 （コンポーネントではなくオブジェクトが渡された）をスローします。プレーンな要素（または独自のコンポーネント）で UI を構築してください。どうしても @splunk/react-ui を使用する必要がある場合は、まず build.mjs に esbuild の相互運用設定を追加してください。

---

レガシーのカスタムビジュアライゼーションの移行

SplunkVisualizationBase から新しいフレームワークへの完全な対応表と、手順ごとの移行方法については、references/migration.md を参照してください。

---

トラブルシューティング

references/troubleshooting.md を参照してください。

---

主な制約事項

• app.conf では、build = <@- buildNumber @> を除き、値をそのまま記述します。このテンプレートタグは意図的なもので、パッケージャーによって値が設定されます。リテラル値に置き換えないでください。
• アプリの id に使用できるのは、英字、数字、ドット、アンダースコアのみです。ドットまたはアンダースコアで始めたり終えたりすることはできません。
• ビジュアライゼーションのスラッグに使用できるのは [a-z0-9_] のみです。ドット、スラッシュ、空白を含む値は拒否してください。解決されたパスが、パストラバーサルのない visualizations/<viz-slug>/ であることを確認してください。
• CSS はビルドプラグインによって iframe に挿入されるため、別途 <link> タグを追加する必要はありません。
• 画像、SVG、フォントはビルド時にデータ URL としてインライン化されるため、直接インポートしてください。
• フォントやその他のアセットを、実行時に外部 URL から読み込まないでください。ローカルに配置し、src/ からインポートして、ビルド時にデータ URL としてインライン化してください。
• ビューモードでは setOptions は無視され、編集モードでのみ機能します。
• オプションには必ずフォールバック値を指定してください。optionsSchema のデフォルト値が実行時に適用されるとは限りません。
• ビジュアライゼーションはサンドボックス化された iframe 内で実行されるため、window.parent にはアクセスできず、ホストページの CSS カスタムプロパティも継承されません。

---

参考資料

• references/api-reference.md — JavaScript および React の API 一覧
• references/config-json.md — config.json のフィールドリファレンス、optionsSchema、editorConfig のエディタータイプ
• references/drilldown-and-tokens.md — ドリルダウンのパターンとトークンの読み取り／書き込み
• references/canvas.md — キャンバスのサイズ設定、インタラクティブ機能、ドリルダウンのパターン
• references/migration.md — レガシーな SplunkVisualizationBase の可視化からの移行
• references/troubleshooting.md — よくあるエラーと解決方法