> ## Documentation Index
> Fetch the complete documentation index at: https://www.qovery.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SigNoz

> SigNoz APM (traces, metrics, logs over OpenTelemetry) with the cluster's Qovery-managed Prometheus metrics federated in

Qovery creates it as a Helm release on the environment's own cluster, as a [Blueprint](https://www.qovery.com/docs/configuration/blueprints.md) service in one of your environments.

| | |
| - | - |
| Catalog name | `helm-signoz` |
| Category | Observability |
| Provider | HELM |
| Engine | helm |
| Major versions (latest release) | `0` (1.0.1) |
| Source | [HELM/signoz/0](https://github.com/Qovery/service-catalog/tree/HELM/signoz/0/1.0.1/HELM/signoz/0) |

> [!TIP]
>
> **New to this?** You don't need to know Kubernetes or Helm. Qovery installs SigNoz on your cluster with Helm and runs it for you: you fill in a form, or paste the prompt below into your coding agent. The values it publishes, listed under Outputs, reach your other services as environment variables. Qovery tells you when a newer version of the Blueprint is available. Check the requirements in the Reference section before you start, and try it first in a development environment.

## Create it

> [tab] Console
>
> 1. Open the environment, then **New service** › **Blueprint**.
> 2. Find **SigNoz** in the catalog and pick the major version.
> 3. Fill in the variables. Required ones are marked; the others use their defaults.
> 4. Create the service, and deploy it now or later.

> [tab] CLI and API
>
> List the catalog to get the latest tag, then create the service from it. `qovery api` signs the requests with your CLI session.
>
> ```bash theme={null}
> ORG_ID="REPLACE_WITH_ORGANIZATION_ID"
> ENV_ID="REPLACE_WITH_ENVIRONMENT_ID"
>
> qovery api "organization/$ORG_ID/blueprint/catalog" | jq '.. | objects | select(.name? == "helm-signoz")'
>
> cat > blueprint.json <<'EOF'
> {
>   "name": "helm-signoz",
>   "tag": "HELM/signoz/0/1.0.1",
>   "icon": "app://qovery-console/signoz",
>   "variables": [
>     {
>       "name": "admin_email",
>       "value": "REPLACE_WITH_ADMIN_EMAIL"
>     },
>     {
>       "name": "admin_password",
>       "value": "REPLACE_WITH_ADMIN_PASSWORD",
>       "is_secret": true
>     }
>   ]
> }
> EOF
> BLUEPRINT_ID=$(qovery api "environment/$ENV_ID/blueprint" --method POST --input - < blueprint.json | jq -r .id)
> rm blueprint.json   # it can hold secret values
> qovery api "blueprint/$BLUEPRINT_ID/deploy" --method POST
> qovery api "blueprint/$BLUEPRINT_ID"   # status of the latest deployment
> ```
>
> Replace each `REPLACE_WITH_` value. Add optional variables to `variables` the same way.

> [tab] Coding agent
>
> Paste this into Claude Code, Cursor, Codex or another coding agent with the [Qovery agent skills](https://www.qovery.com/docs/getting-started/quickstart/agent-skills.md) installed (`curl -fsSL https://skill.qovery.com/install.sh | bash`).
>
> ```text Prompt wrap theme={null}
> Add the Qovery Blueprint SigNoz (helm-signoz) to one of my Qovery environments and deploy it. Ask me for admin_email and admin_password.
> Ask me before deploying to a production environment.
> Docs: https://www.qovery.com/docs/configuration/blueprints/helm-signoz.md
> ```

You don't add any file to your repository. Qovery creates the Blueprint from the Console or the API.

## Variables and outputs

Generated from `qbm.yml` at `HELM/signoz/0/1.0.1`, the manifest the Console form is built from.

> [accordion] All 15 variables
>
> | Name | Type | Required | Default | Secret | Description |
> | - | - | - | - | - | - |
> | `admin_email` | string | Yes | | | Root user's email. Changing it and redeploying updates it. |
> | `admin_password` | string | Yes | | Yes | 12–72 ASCII chars with an uppercase, a lowercase, a digit and a symbol; no spaces, ' or ;. Changing it and redeploying resets it. |
> | `org_name` | string | | `SigNoz` | | Organization SigNoz creates on first start. Later changes have no effect (rename it in SigNoz settings). |
> | `external_url` | string | | | | Unset = links in alert notifications point to [http://localhost:8080](http://localhost:8080). Set the URL users reach SigNoz on (e.g. [https://signoz.example.com](https://signoz.example.com)) so alert links work. |
> | `usage_reporting` | string | | `false` | | Send anonymous usage statistics to the SigNoz team |
> | `prometheus_federation` | string | | `true` | | Copy cluster Prometheus metrics into SigNoz for PromQL panels and alerts, from install onwards |
> | `prometheus_address` | string | | `prometheus-operated.prometheus.svc.cluster.local:9090` | | Leave the default on AWS and Scaleway. On GKE and AKS use prometheus-operated.qovery.svc.cluster.local:9090 (host:port, no scheme). |
> | `federation_match` | string | | `{job=~"kubelet\|kube-state-metrics\|node-exporter"}` | | Prometheus series selector of what to copy. The default covers container, pod and node metrics; widen it with care, every series is stored again in ClickHouse. |
> | `federation_interval` | string | | `60s` | | How often metrics are copied from Prometheus. Go duration, at least 15s (e.g. 30s, 1m). |
> | `clickhouse_storage_size` | string | | `50Gi` | | Kubernetes quantity (e.g. 50Gi) holding every trace, log and metric. Can only grow, on a storage class that allows expansion. |
> | `storage_class` | string | | | | Unset = the cluster's default, for every SigNoz volume. Set at creation: a volume cannot change class, so a later change fails the deploy. |
> | `clickhouse_cpu` | string | | `500m` | | CPU request, as a Kubernetes quantity (e.g. 500m, 2) |
> | `clickhouse_memory` | string | | `4Gi` | | Limit for ClickHouse, which runs the queries; requests are a quarter. Kubernetes quantity in Mi or Gi. |
> | `collector_memory` | string | | `4Gi` | | OpenTelemetry collector limit, in Mi or Gi. Federating the default selector needs about 2Gi on a mid-size cluster. |
> | `signoz_memory` | string | | `1Gi` | | Limit for the UI and query server, in Mi or Gi |

Outputs become environment variables that other services in the environment can use. By default Qovery also creates an alias for each output, prefixed with the Blueprint's name; see [Aliases Qovery creates for outputs](https://www.qovery.com/docs/configuration/environment-variables.md#aliases-qovery-creates-for-outputs) for the naming rules and the cases where no alias is created.

> [accordion] All 2 outputs
>
> | Name | Secret | Description |
> | - | - | - |
> | `signoz_ui_service` | | In-cluster SigNoz UI and API service (signoz, port 8080) |
> | `otlp_endpoint` | | In-cluster OTLP endpoint: signoz-otel-collector, 4317 (gRPC), 4318 (HTTP) |

## Reference

From the Blueprint's [README](https://github.com/Qovery/service-catalog/blob/HELM/signoz/0/1.0.1/HELM/signoz/0/README.md).

Deploys [SigNoz](https://signoz.io/docs/) `v0.143.0` with the official `signoz/signoz` Helm chart (`0.143.0`): the SigNoz UI and query server, an OpenTelemetry collector, ClickHouse (through the Altinity operator) and ZooKeeper.

Applications send traces, metrics and logs over OTLP to the in-cluster collector:

| Protocol | Endpoint |
| - | - |
| gRPC | `signoz-otel-collector.<environment namespace>.svc.cluster.local:4317` |
| HTTP | `http://signoz-otel-collector.<environment namespace>.svc.cluster.local:4318` |

With `prometheus_federation=true` (the default), the collector also copies container, pod and node metrics from the Prometheus Qovery installs with cluster metrics, so they can be queried with PromQL in SigNoz dashboards and alerts. Only data from the install onwards is copied; the history stays in Prometheus/Thanos.

### Credentials

The admin is SigNoz's **root user**, provisioned from `admin_email` and the sensitive `admin_password` entered in the Qovery console. SigNoz reconciles it on every start: changing either value and redeploying updates the admin's email or resets the password. The root user cannot be deleted, renamed or have its password changed from the SigNoz UI; use the Qovery form.

`org_name` is only used when SigNoz creates the organization. The organization id is pinned, so a later change of `org_name` neither renames the organization nor creates a second one.

The password must be 12 to 72 ASCII characters (bcrypt's limit) and contain an uppercase letter, a lowercase letter, a digit and one of ``~!@#$%^&*()_+`-={}|[]\:"<>?,./``, with no other characters (no spaces, single quotes `'` or semicolons; double quotes are allowed). The form rejects anything else: SigNoz would refuse it and never become ready.

### Variables

#### Required

| Name | Type | Sensitive | Description |
| - | - | - | - |
| `admin_email` | string | | Email of the SigNoz admin (root user). Changing it and redeploying updates the admin's email. |
| `admin_password` | string | yes | SigNoz admin password: 12 to 72 characters with an uppercase letter, a lowercase letter, a digit and one of \~!@#\$%^&\*()\_+\`-=\{}\|\[]:"\<>?,./ ASCII only; no spaces, single quotes or semicolons. Changing it and redeploying resets it. |

#### Optional

| Name | Type | Default | Description |
| - | - | - | - |
| `org_name` | string | `SigNoz` | Name of the organization SigNoz creates on first start. Set once: changing it later has no effect (rename the organization in SigNoz settings). |
| `external_url` | string | — | Unset = links in alert notifications point to `http://localhost:8080`. Set the URL users reach SigNoz on so alert links work. |
| `usage_reporting` | string | `false` | Send anonymous usage statistics to the SigNoz team (`true`/`false`). |
| `prometheus_federation` | string | `true` | Copy metrics from the cluster's Prometheus into SigNoz, so PromQL panels and alerts in SigNoz can use them. Only data from the install onwards. |
| `prometheus_address` | string | `prometheus-operated.prometheus.svc.cluster.local:9090` | Leave the default on AWS and Scaleway clusters: the Prometheus Qovery installs with cluster metrics. On GKE and AKS use prometheus-operated.qovery.svc.cluster.local:9090. host:port, no scheme. |
| `federation_match` | string | `{job=~"kubelet\|kube-state-metrics\|node-exporter"}` | Prometheus series selector of what to copy. Every series is stored again in ClickHouse; widen it with care. |
| `federation_interval` | string | `60s` | How often metrics are copied, in `s` or `m`. At least `15s`. |
| `clickhouse_storage_size` | string | `50Gi` | Volume holding every trace, log and metric. Valid Kubernetes quantity. It can only grow after creation, on a storage class that allows expansion. |
| `storage_class` | string | — | Unset = the cluster's default storage class, for every SigNoz volume. Choose it when creating the service: a volume cannot change class, so changing it later fails the deploy. |
| `clickhouse_cpu` | string | `500m` | CPU request for ClickHouse. |
| `clickhouse_memory` | string | `4Gi` | Memory limit for ClickHouse; requests are a quarter of it. `Gi` or `Mi`. |
| `collector_memory` | string | `4Gi` | Memory limit for the OpenTelemetry collector. Federation of the default selector needs about 2Gi on a mid-size cluster. Valid Kubernetes quantity. |
| `signoz_memory` | string | `1Gi` | Memory limit for the SigNoz UI and query server. Valid Kubernetes quantity. |

### Outputs

| Name | Description |
| - | - |
| `signoz_ui_service` | In-cluster SigNoz UI and API service (`signoz`, port 8080) |
| `otlp_endpoint` | In-cluster OTLP endpoint (`signoz-otel-collector`, ports 4317 gRPC and 4318 HTTP) |

### Accessing SigNoz

The SigNoz UI is published on the URL Qovery generates for the service (Helm service → Overview → Links), over HTTPS. Log in with `admin_email` and `admin_password`. Set `external_url` to that URL so links in alert notifications point to it. The OTLP endpoints stay in-cluster only.

On a Qovery engine older than the one that added blueprint ports (QOV-2335), the service is created without a public URL. Reach it with a port-forward instead:

```sh theme={null}
kubectl port-forward -n <environment namespace> svc/signoz 8080:8080
```

### Deleting the service

**On engines without QOV-2336, deleting the service hangs until you clear one finalizer.** From that engine release on, the engine deletes the release's custom resources before uninstalling it and lets the ClickHouse operator clean up (about 30s), so no manual step is needed. If the operator cannot finish within 5 min, the deletion fails and names the stuck resource instead of hanging; the command below then unblocks it. `helm uninstall` removes the ClickHouse operator in the same pass as the `ClickHouseInstallation` it manages. That resource carries the operator's finalizer, and with the operator gone nothing removes it: the resource stays `Terminating` and the Qovery deletion waits on it until the 30-minute Helm timeout.

Right after starting the deletion, from the service's namespace:

```sh theme={null}
kubectl -n <environment namespace> patch clickhouseinstallation signoz-clickhouse \
  --type=merge -p '{"metadata":{"finalizers":[]}}'
```

The deletion then completes within a minute. Deleting the whole environment needs the same step: the namespace cannot go away while the resource is stuck.

**The data volumes outlive the service.** ClickHouse (`clickhouse_storage_size`), ZooKeeper (8Gi) and SigNoz (1Gi) volumes belong to StatefulSets, which Kubernetes never deletes with their pods. They stay, and bill, until the environment is deleted or you remove them:

```sh theme={null}
kubectl -n <environment namespace> delete pvc \
  data-volumeclaim-template-chi-signoz-clickhouse-cluster-0-0-0 \
  data-signoz-zookeeper-0 signoz-db-signoz-0
```

Recreating the service in the same environment before that reuses the old volumes, data and admin included.

### Notes

* **Sizing.** The defaults request about 0.8 vCPU and 4.1Gi of memory with federation on (ClickHouse 500m/1Gi, collector 100m/2.5Gi, SigNoz 100m/256Mi, ZooKeeper 50m/256Mi, operator 30m/96Mi), with memory limits up to about 10.4Gi. The schema migration job, which runs on install and before each upgrade, adds 50m/128Mi (limit 512Mi) while it runs. Without federation the collector requests 512Mi, for about 2.1Gi in total.
* **Federation cost.** One `/federate` pull of the default selector is tens of MB on a busy cluster; the collector holds it in memory, which is where its memory goes. Narrow `federation_match` or raise `federation_interval` on large clusters.
* **Metric names are Prometheus names** (`container_cpu_usage_seconds_total`, `kube_pod_info`, …), queried with PromQL panels. SigNoz's built-in Infrastructure pages expect the OpenTelemetry names of its own `k8s-infra` agent and stay empty. No dashboard is preloaded: the chart offers no hook to create one.
* **Logs** come only from what applications send over OTLP. Pod logs stay in Qovery's Loki; this blueprint does not install a log agent on the nodes.
* **Retention** is SigNoz's default (traces and logs 15 days, metrics 30 days), changed in Settings → General.
* **Volume settings are creation-time.** Kubernetes forbids changing a bound volume's class, so an update that changes `storage_class` fails with `spec is immutable after creation`. `clickhouse_storage_size` can only grow.
* **Cluster-wide resources** (`allowClusterWideResources: true`): the ClickHouse operator CRDs, installed from the chart's `crds/` once per cluster and shared by every SigNoz install, and a ClusterRole the collector uses to read Kubernetes metadata. The operator itself is pinned to its own namespace (`WATCH_NAMESPACES`), so several SigNoz installs can share a cluster.
* **Fixed resource names**: `signoz`, `signoz-otel-collector`, `signoz-clickhouse`, `signoz-zookeeper`. The chart derives ClickHouse's names from the release, and the operator appends `-deploy-confd-cluster-0-0`: with Qovery's `helm-z<id>-<service>` release names, a service name over 7 characters exceeded Kubernetes' 63-character limit and ClickHouse was never created. Deploy one SigNoz blueprint per environment.
* The rendered values, admin password included, are stored in the Helm service's values override, like every Helm blueprint's inputs.
* Chart pinned to `0.143.0`. SigNoz is still `0.x`, hence the `HELM/signoz/0` directory; it is the official chart, not Bitnami.


## Related topics

- [Blueprints](https://www.qovery.com/docs/configuration/blueprints.md)
- [Get Sign up information](https://www.qovery.com/docs/api-reference/user-sign-up/get-sign-up-information.md)
- [Send Sign Up request](https://www.qovery.com/docs/api-reference/user-sign-up/send-sign-up-request.md)
- [Search user signups](https://www.qovery.com/docs/api-reference/admin/search-user-signups.md)
- [Troubleshooting](https://www.qovery.com/docs/getting-started/troubleshoot/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.