菜单
Diagnostic reference for Splunk custom viz failures — 54 rules organized by severity (fatal, broken, rejected, cosmetic) plus error diagnosis flowchart. Loaded automatically when editing viz source files.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Validates, packages, and (on failure) diagnoses a splunk-custom-viz app. Make sure to use this skill after cv-create writes the source files, or whenever the user asks to package, tar, build, or deploy a Splunk custom viz pack. Produces .tar.gz (Classic) or .spl (Extension API) or both. Grep-based validation — no node_modules required. Includes 54 diagnostic rules loaded on demand when a viz fails.
Generates Splunk custom visualization code — formatter HTML, Canvas 2D source, and app config. Includes copy-paste templates with correct Splunk-specific syntax for ad-hoc search compatibility.
Expert guidance for building, customising, and packaging Splunk add-ons using the UCC (Universal Configuration Console) Framework. Use this skill whenever the user mentions: UCC, splunk add-on, TA (Technology Add-on), globalConfig, ucc-gen, modular inputs, Splunk add-on development, addonfactory, splunktaucclib, or needs to create/edit/build/package/validate a Splunk add-on. Also trigger for tasks involving inputs pages, configuration pages, alert actions, OAuth in Splunk, custom REST handlers, or any work with globalConfig.json / globalConfig.yaml files.
Use this skill whenever the user wants to build, customise, or extend Splunk visualisations and dashboards using the Splunk UI Toolkit (SUIT). Triggers include: creating a Splunk React app with @splunk/create, building custom visualisations or chart types for Dashboard Studio or the Unified Dashboard Framework (UDF), editing Dashboard JSON definitions (dataSources, visualizations, layout, inputs, tokens, expressions), wiring up tokens and drilldown interactivity, adding @splunk/react-ui components (Button, Card, Table, Layout, etc.) to a Splunk page, theming with SplunkThemeProvider, and packaging Splunk apps as .spl files. Also trigger for any question about when to choose Dashboard Studio vs the Dashboard Framework vs Classic Simple XML, or how to migrate between them. Always use this skill for SUIT topics even if the user only mentions "Splunk dashboard", "splunk.column", "DashboardCore", "preset", "drilldown token", "@splunk/react-ui", or "splunk app React".
SPL syntax traps and categorized command index for all Splunk search commands. Load BEFORE writing any SPL — dashboards, ad-hoc searches, alerts, saved searches, generators. Top 20+ silent-fail traps ranked by frequency, plus categorized command index with when-to-use descriptions. For full syntax on any command, read reference/<command>.md from this plugin.
Produces a single-file HTML mockup and a structured DESIGN-LOCK.md for a Splunk custom viz pack. Make sure to use this skill after cv-scope, or whenever the user wants to design a Splunk custom viz pack with high visual quality. HTML-first design workflow: writes a designer-grade mockup the user can open in a browser, then extracts a structured visual contract for cv-create to port to Splunk code. Includes mandatory pre-flight commitment block, 8 absolute bans against AI-slop patterns, and a self-administered Slop Test.
| name | vp-debug |
| description | Diagnostic reference for Splunk custom viz failures — 54 rules organized by severity (fatal, broken, rejected, cosmetic) plus error diagnosis flowchart. Loaded automatically when editing viz source files. |
| when_to_use | Use when a viz fails to load, renders incorrectly, or validate_viz.sh reports errors. Triggers on 'viz broken', 'script error', 'debug viz', 'why does my viz', 'formatter not working', 'blank panel'. |
| paths | */visualizations/*/visualization_source.js, */visualizations/*/formatter.html |
These 54 rules were learned from real bugs across 30+ shipped viz apps. They explain WHY things fail and HOW to fix them.
For code GENERATION, use vp-viz — it has all rules baked into the templates. This skill explains the reasoning behind those rules.
Viz shows placeholder icon (bar chart in grey box)
├── Console: "Script error for .../visualization.js"
│ ├── File not found? → F9 (wrong directory)
│ ├── Webpack IIFE? → F11 (use flat AMD)
│ ├── jQuery used? → F10 (no $el in DS v2)
│ └── Double AMD wrapper? → F6 (source uses define())
├── Console: "Unknown output mode: undefined"
│ ├── getInitialDataParams missing? → F4 (required method)
│ └── outputMode as property? → F4 (must be in method)
├── Console: "X is not a function"
│ ├── _render? → C6 (wrong method name in reflow)
│ ├── addClass? → F10 (jQuery)
│ └── constructor? → F7 (must use extend object literal)
├── No console errors but blank
│ ├── setupCanvas with wrapper div? → B17
│ ├── this.el has width/height set? → B17
│ ├── formatData returns null? → B15
│ └── Canvas dimensions 0×0? → B17
├── Values show "null" or "undefined" → B21
├── Timestamps show "Jan 1" or "Invalid Date" → B19
├── Wrong theme (dark on light) → B20
├── Background color shows dark bg in light mode → THM-05 (opt('backgroundColor') inside dark branch only — see theme-template.md THM-05)
├── Gauge/arc overflows panel → B8
├── Formatter settings have no effect → B10 (VIZ_NAMESPACE)
├── Settings appear but don't save → B7 (value= not default=)
├── Color picker ignored → B5 (type="custom" required)
└── Changes not taking effect → C8 (build number + hard refresh)
Console noise to IGNORE (Splunk framework, not your bugs):
SecurityError: Failed to read 'cookie' — sandboxed iframeContent Security Policy directive 'img-src' — Splunk CSP502 Connection refused on orchestrator/v1/spl2/enabled| Rule | Summary |
|---|---|
| F1 | Webpack must target ES5 |
| F2 | Fonts must be base64 data URIs |
| F3 | Source must be pure ES5 |
| F4 | getInitialDataParams must use ROW_MAJOR_OUTPUT_MODE |
| F5 | Only externalize what you import |
| F6 | Source MUST use require(), NEVER define() |
| F7 | MUST use extend({...}) object literal |
| F8 | Images must be bundled, never external URLs |
| F9 | Vizs in appserver/static/visualizations/, NOT default/ |
| F10 | No jQuery — use standard DOM APIs |
| F11 | Webpack 5 IIFE may fail — flat AMD alternative |
| F12 | Formatter must use Splunk components, never raw HTML |
See references/broken-rules.md
| Rule | Summary |
|---|---|
| B1 | Canvas font rendering requires explicit wait |
| B2 | HiDPI canvas scaling is mandatory |
| B3 | getOption helper is mandatory |
| B4 | Never read config in formatData |
| B5 | Formatter section labels + type="custom" on color picker |
| B6 | Canvas shadow state leaks |
| B7 | JS defaults must match formatter value= (NEVER default=) |
| B8 | Auto-scale by default + gauge arc constraint |
| B9 | Dashboard Studio type format |
| B10 | {{VIZ_NAMESPACE}} in formatter — NEVER hardcoded namespace |
| B11 | parseFloat truncates string values |
| B12 | Gauge colors must match brand |
| B13 | Canvas background must use clearRect |
| B14 | Variables in _draw() not accessible from sub-methods |
| B15 | Always include formatData in extend object |
| B16 | Every visual property configurable via formatter |
| B17 | setupCanvas MUST use this.el with clientWidth |
| B18 | Theme auto-detect via getCurrentTheme() |
| B19 | new Date() fails in sandboxed iframe |
| B20 | Theme MUST default to 'auto' with detectTheme() |
| B21 | Always null-guard before String() conversion |
| B22 | hexFromSplunk — color picker returns integers not hex |
| B23 | Light theme needs independent design, not dark inversion |
See references/rejected-rules.md
See references/interactive-cosmetic.md
| Symptom | Most likely rule |
|---|---|
| Script error on load | F9, F6, F11 |
| Blank panel, no errors | B17, B15 |
| Settings don't save | B10, B7 |
| Wrong colors in light mode | B20, B18, B23 |
| Color picker ignored in ad-hoc | B22 |
| Text invisible in light theme | B23 |
| "null" visible in text | B21 |
| Gauge overflows panel | B8 |
| Timestamps wrong | B19 |
| AppInspect failure | R1-R8 |
| Background color wrong in light mode | THM-05 / B23 — check opt('backgroundColor') read unconditionally, not inside dark branch (see theme-template.md THM-05) |
| FAIL E01-E05 (Extension API config/viz failure) | validate_viz.sh E-codes — check config.json optionsSchema + visualization.js addDataSourcesListener |
| FAIL A01-A02 (preview.png missing or wrong size) | run python3 generate_previews.py (116x76) — see vp-create Step 3b |
| FAIL A03-A04 (appIcon.png missing or wrong size) | run node generate_assets.js — see vp-create Step 3b |
| Animation has no effect | AF-01 — opt() called inside a helper; pass computed values as params (see animation-recipes.md AF-01) |
Scope note (W-20):
check_design.js(D01-D11 codes) validatesformatter.htmlonly. Extension API vizs (visualization.js) bypass D01-D11 checks entirely — if a D-code appears missing for an Extension viz, that is expected behavior, not a doc gap. Verify Extension API correctness via E01-E05 codes fromvalidate_viz.sh.