Getting Started with SeriesMarker — Quick Setup & TipsSeriesMarker is a lightweight tool for tagging, organizing, and visualizing time-series and categorical data across dashboards and reports. This guide walks you through installation, basic concepts, quick setup, common workflows, and practical tips to get the most out of SeriesMarker.
What is SeriesMarker?
SeriesMarker is a tagging and visualization helper for series-based data — it simplifies how you label, group, and display multiple series (time series, categorical series, or metric streams) in charts and dashboards. Think of it as a middle layer that helps instruments, analytics, and visualization libraries speak the same language about series metadata.
Quick setup
1. Prerequisites
- Node.js 14+ (for the CLI and local dev tools) or a comparable runtime if using a different distribution.
- A charting/visualization library (e.g., Chart.js, D3, Plotly) if you plan to render visuals.
- Basic familiarity with JSON or YAML for configuration.
2. Installation (CLI / SDK)
If SeriesMarker provides an npm package, install with:
npm install seriesmarker
Or add the SDK to your Python environment:
pip install seriesmarker
(Replace the commands above with the package manager appropriate for your environment.)
3. Initial configuration
Create a configuration file (seriesmarker.config.json or seriesmarker.yaml) at your project root. A minimal JSON example:
{ "defaultColorScheme": "viral", "groupBy": ["service", "region"], "presets": { "errorSeries": { "color": "#E53E3E", "lineStyle": "dashed", "priority": 10 } } }
Load this config in code:
const SeriesMarker = require('seriesmarker'); const sm = new SeriesMarker('./seriesmarker.config.json');
Core concepts
- Series: a named set of observations over time or categories (e.g., “cpu_usage”, “page_views”).
- Marker: metadata attached to a series (color, label, group, priority).
- Grouping: rules to cluster series into lanes, facets, or chart overlays.
- Presets: reusable marker templates for consistency across reports.
- Priority: ordering rule for rendering and legend positioning.
Common workflows
Tagging and labeling series
Programmatically attach markers to your series before rendering:
sm.mark('service-A.cpu', { color: '#3182CE', label: 'Service A CPU', group: 'infrastructure' }); sm.mark('service-B.errors', { color: '#E53E3E', label: 'Service B Errors', group: 'errors', lineStyle: 'dashed' });
Automatic grouping and faceting
Use config rules to auto-group by fields:
"groupBy": ["environment", "region"]
SeriesMarker will create facets for each combination (e.g., prod/us-east, staging/eu-west).
Integrating with Charting Libraries
Transform SeriesMarker output to the format your charting library expects:
const chartData = sm.toChartJS(seriesArray); renderChart(ctx, chartData);
Tips & best practices
- Use presets for consistent visual language across teams (errors in red, warnings in amber).
- Keep group keys shallow — two or three levels (e.g., service → region) balance flexibility and usability.
- Prioritize series logically: put user-impacting metrics higher in legends/dashboards.
- Color contrast: pick accessible palettes and test for colorblindness.
- Use dashed/dotted lines for less critical series instead of faint colors, which can be hard to see.
Troubleshooting
- If series don’t appear grouped as expected, verify series keys match your groupBy fields exactly (case-sensitive).
- Overlapping colors: increase priority for critical series or use patterns/line styles.
- Performance: when handling thousands of series, paginate or lazy-load facets to keep UI responsive.
Example: End-to-end quick demo
- Install SeriesMarker (npm/pip).
- Add seriesmarker.config.json with presets and groupBy rules.
- Ingest series and call sm.mark(…) for key series.
- Convert to chart format (sm.toChartJS / sm.toPlotly) and render.
- Iterate on colors and priorities based on feedback.
Further reading and next steps
- Create shared presets for your organization.
- Integrate SeriesMarker into CI to enforce visual standards.
- Explore advanced features: conditional rules, anomaly highlighting, and export templates.
If you want, I can convert the examples to Python, produce a full sample project, or create a palette of accessible color presets.