Use this skill when working with SigNoz - open-source observability platform for application monitoring, distributed tracing, log management, metrics, alerts, and dashboards. Triggers on SigNoz setup, OpenTelemetry instrumentation for SigNoz, sending traces/logs/metrics to SigNoz, creating SigNoz dashboards, configuring SigNoz alerts, exception monitoring, and migrating from Datadog/Grafana/New Relic to SigNoz.
Use this skill when working with SigNoz - open-source observability platform for application monitoring, distributed tracing, log management, metrics, alerts, and dashboards. Triggers on SigNoz setup, OpenTelemetry instrumentation for SigNoz, sending traces/logs/metrics to SigNoz, creating SigNoz dashboards, configuring SigNoz alerts, exception monitoring, and migrating from Datadog/Grafana/New Relic to SigNoz.
[{"url":"https://signoz.io/docs/introduction/","accessed":"2026-03-14T00:00:00.000Z","description":"SigNoz platform overview and feature summary"},{"url":"https://signoz.io/docs/instrumentation/","accessed":"2026-03-14T00:00:00.000Z","description":"Language instrumentation guides"}]
license
MIT
maintainers
[{"github":"maddhruv"}]
When this skill is activated, always start your first response with the 🧢 emoji.
SigNoz
SigNoz is an open-source observability platform that unifies traces, metrics, and
logs in a single backend powered by ClickHouse. Built natively on OpenTelemetry, it
provides APM dashboards, distributed tracing with flamegraphs, log management with
pipelines, custom metrics, alerting across all signals, and exception monitoring -
all without vendor lock-in. SigNoz is available as a managed cloud service or
self-hosted via Docker or Kubernetes.
When to use this skill
Trigger this skill when the user:
Wants to set up or configure SigNoz (cloud or self-hosted)
Needs to instrument an application to send traces, logs, or metrics to SigNoz
Asks about OpenTelemetry Collector configuration for SigNoz
Wants to create dashboards, panels, or visualizations in SigNoz
Needs to configure alerts (metric, log, trace, or anomaly-based) in SigNoz
Asks about SigNoz query builder syntax, aggregations, or filters
Wants to monitor exceptions or correlate traces with logs in SigNoz
Is migrating from Datadog, Grafana, New Relic, or ELK to SigNoz
Do NOT trigger this skill for:
General observability concepts without SigNoz context (use the observability skill)
OpenTelemetry instrumentation not targeting SigNoz as the backend
Setup & authentication
SigNoz Cloud
Sign up at https://signoz.io/teams/ to get a cloud instance. You will receive:
A region endpoint (e.g. ingest.us.signoz.cloud:443)
A SIGNOZ_INGESTION_KEY for authenticating data
Self-hosted deployment
# Docker Standalone (quickest for local/dev)
git clone -b main https://github.com/SigNoz/signoz.git && cd signoz/deploy/
docker compose -f docker/clickhouse-setup/docker-compose.yaml up -d
# Kubernetes via Helm
helm repo add signoz https://charts.signoz.io
helm install my-release signoz/signoz
Self-hosted supports Docker Standalone, Docker Swarm, Kubernetes (AWS/GCP/Azure/
DigitalOcean/OpenShift), and native Linux installation.
Environment variables
# For cloud - set these in your OTel Collector or SDK exporter config
SIGNOZ_INGESTION_KEY=your-ingestion-key
OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.<region>.signoz.cloud:443
OTEL_EXPORTER_OTLP_HEADERS=signoz-ingestion-key=<your-ingestion-key>
Core concepts
SigNoz uses OpenTelemetry as its sole data ingestion layer. All telemetry
(traces, metrics, logs) flows through an OTel Collector which receives data
via OTLP (gRPC on port 4317, HTTP on 4318), processes it with batching and
resource detection, and exports it to SigNoz's ClickHouse storage backend.
The data model has three pillars:
Traces - Distributed request flows visualized as flamegraphs and Gantt charts.
Each trace contains spans with attributes, events, and status codes.
Metrics - Time-series data from application instrumentation (p99 latency, error
rates, Apdex) and infrastructure (CPU, memory, disk, network via hostmetrics receiver).
Logs - Structured log records ingested via OTel SDKs, FluentBit, Logstash, or
file-based collection. Processed through log pipelines for parsing and enrichment.
All three signals correlate - traces link to logs via trace IDs, and exceptions embed
in spans. The Query Builder provides a unified interface for filtering, aggregating,
and visualizing across all signal types.
File-based - Use FluentBit or Logstash to tail log files and forward via OTLP
Stdout/collector - Pipe container stdout to the OTel Collector's filelog receiver
# FluentBit output to SigNoz via OTLP
[OUTPUT]
NameopentelemetryMatch*Hostingest.<region>.signoz.cloudPort443Headersignoz-ingestion-key<your-key>TlsOnTls.verifyOn
Log pipelines in SigNoz can parse, transform, enrich, drop unwanted logs, and
scrub PII before storage.
Create dashboards and panels
Navigate to Dashboards > New Dashboard. Add panels using the Query Builder:
Select signal type (metrics, logs, or traces)
Add filters (e.g. service.name = my-app)
Choose aggregation (Count, Avg, P99, Rate, etc.)
Group by attributes (e.g. method, status_code)
Set visualization type (time series, bar, pie chart, table)
Use {{attributeName}} in legend format for dynamic labels. Multiple queries
can be combined with mathematical functions (log, sqrt, exp, time shift).
SigNoz provides pre-built dashboard JSON templates on GitHub that can be imported.
Configure alerts
SigNoz supports six alert types:
Metrics-based - threshold on any metric
Log-based - patterns, counts, or attribute values
Trace-based - latency or error rate thresholds
Anomaly-based - automatic anomaly detection
Exceptions-based - exception count or type thresholds
Apdex alerts - application performance index
Notification channels include Slack, PagerDuty, email, and webhooks. Alerts
support routing policies and planned maintenance windows. A Terraform provider
is available for infrastructure-as-code alert management.
Monitor exceptions
Exceptions are auto-recorded for Python, Java, Ruby, and JavaScript. For other
languages, record manually:
from opentelemetry import trace
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("operation") as span:
try:
risky_operation()
except Exception as ex:
span.record_exception(ex)
span.set_status(trace.StatusCode.ERROR, str(ex))
raise
Exceptions group by service name, type, and message. Enable
low_cardinal_exception_grouping in the clickhousetraces exporter to group
only by service and type (reduces high cardinality from dynamic messages).
Query with the Query Builder
# Filter: service.name = demo-app AND severity_text = ERROR
# Aggregation: Count
# Group by: status_code
# Aggregate every: 60s
# Order by: timestamp DESC
# Limit: 100
Supported aggregations: Count, Count Distinct, Sum, Avg, Min, Max, P05-P99,
Rate, Rate Sum, Rate Avg, Rate Min, Rate Max. Filters use =, !=, IN,
NOT_IN operators combined with AND logic.
Advanced functions: EWMA smoothing (3/5/7 periods), time shift comparison,
cut-off min/max thresholds, and chained function application.
Gotchas
OTel SDK must be initialized before any other imports - If application code imports a DB driver, HTTP client, or framework before the OTel SDK is initialized, those libraries will not be auto-instrumented. In Node.js, use --require ./instrument.js to load the SDK before the app. In Python, call sentry_sdk.init() (or the OTel equivalent) at the top of the entry point.
gRPC (4317) is blocked by many cloud firewalls by default - Outbound gRPC traffic on port 4317 is frequently blocked by corporate firewalls and cloud security groups. If traces are not arriving, switch the exporter to OTLP/HTTP on port 4318 (OTLPTraceExporter with http:// URL) as a first debug step.
Missing service.name attribute makes all data unidentifiable - If OTEL_SERVICE_NAME is not set and the SDK is not explicitly configured with a service name, all telemetry arrives in SigNoz grouped under a generic name or unknown_service. Set OTEL_SERVICE_NAME in your environment or SDK config before deploying.
Self-hosted ClickHouse storage fills up silently - SigNoz self-hosted deployments do not have built-in disk alerting. ClickHouse will fill available disk and stop accepting writes without warning. Configure a disk utilization alert on the host and set a data retention policy in SigNoz settings (default is 15 days for traces).
High-cardinality span attributes break dashboards - Adding user IDs, request IDs, or raw query strings as span attribute keys (not values) creates unbounded cardinality in ClickHouse and makes dashboards unusable. Cardinality should live in attribute values, not keys. Use a fixed set of keys like user.id, request.id with variable values.
Error handling
Error
Cause
Resolution
No data in SigNoz after setup
OTel Collector not reaching SigNoz endpoint
Add a debug exporter to the collector config to verify telemetry is received locally; check endpoint URL and ingestion key
Port 4317/4318 already in use
Another process bound to OTLP ports
Stop conflicting process or change collector receiver ports
context deadline exceeded
Network/firewall blocking gRPC to SigNoz cloud
Verify outbound 443 is open; check TLS settings in exporter config
High cardinality exceptions
Dynamic exception messages creating too many groups
Enable low_cardinal_exception_grouping in clickhousetraces exporter
Missing host metrics
hostmetrics receiver not configured or Docker volume not mounted
Add hostmetrics receiver with scrapers; set root_path: /hostfs for Docker deployments
References
For detailed content on specific sub-domains, read the relevant file from the
references/ folder:
references/instrumentation.md - Language-specific instrumentation guides and
setup patterns (read when instrumenting a specific language)
references/otel-collector.md - Advanced OTel Collector configuration, receivers,
processors, and exporters (read when customizing the collector pipeline)
references/query-builder.md - Full query builder syntax, aggregation functions,
and advanced analysis features (read when building complex queries or dashboards)
Only load a references file if the current task requires it - they are long and
will consume context.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
