Custom dashboards
Use the helm/app-charts/signoz-dashboards sample chart to install your own
dashboards into SigNoz and repeat the import with Helm upgrades. Keep your JSON
dashboard definitions with the chart in your application's source control.
Install it as a separate Helm release from the OBaaS platform release.
Prerequisites
- A healthy OBaaS SigNoz instance, including its ClickHouse connection.
- Helm and
kubectlconfigured for the target cluster. - The namespace and Helm release name of your OBaaS instance.
- An existing SigNoz credential Secret containing
emailandpassword.
Install the dashboard chart in the same namespace as OBaaS. The default credential
Secret is signoz-authn; use the Secret configured for your instance if it has a
different name. See Access SigNoz for connection and credential
instructions.
Add your dashboard files
- Export each custom dashboard as JSON from SigNoz.
- Place each file directly in
helm/app-charts/signoz-dashboards/dashboards/. - Remove
sample-application.jsonwhen replacing the empty sample dashboard. - Give each dashboard a unique, application-specific title.
The chart includes only dashboards/*.json; it does not include subdirectories.
Each JSON file becomes a ConfigMap. For example, orders.json creates the
ConfigMap orders. Names are normalized when needed and shortened to at most
63 characters, with a hash suffix to distinguish changed names. Use distinct
filenames across dashboard releases in the same namespace because ConfigMap
names are based on filenames rather than Helm release names.
Each JSON file must fit within Kubernetes' 1 MiB ConfigMap data limit. The complete chart must also fit within Helm's release storage limits; splitting files into individual ConfigMaps does not remove the aggregate limit.
Dashboard formats
The importer detects the dashboard API supported by the deployed SigNoz instance:
- Older instances, including OBaaS 2.1.0's SigNoz, use the V1 dashboard API and
JSON exports with
version: "v4"or"v5". The dashboard title istitle. - Newer instances use the V2 API and Perses exports with
schemaVersion: "v6". The dashboard title isspec.display.name.
Use V1 exports when the same definitions need to run on both older and newer instances. Newer SigNoz can convert V1 payloads submitted to its V2 create endpoint. This compatibility is transitional; for future SigNoz upgrades, re-export dashboards in the supported format. V2 files cannot be imported into a V1 instance and are rejected before any dashboards are deleted.
Configure the chart
Create a values file, for example my-dashboards-values.yaml, containing the
OBaaS release name and credential Secret reference:
signoz:
releaseName: obaas
auth:
existingSecret: signoz-authn
Replace obaas with your actual OBaaS platform release name, not the release name
you will use for the dashboard chart. Keep passwords out of the values file.
The Job runs a Python standard-library importer on
container-registry.oracle.com/os/oraclelinux:9. It waits for SigNoz, discovers
the organization through /api/v2/sessions/context using the credential Secret's
email, logs in, and imports dashboards through the detected dashboard API.
If the Secret contains a non-empty orgID key, that value takes precedence over
discovery. Accounts belonging to multiple organizations must supply this key to
select an organization explicitly. The Secret must contain email and password
in either case.
For private registries, configure image.repository, image.tag, and
imagePullSecrets. Replacement images must provide Python 3 and its standard
library. No runtime package installation is needed.
Install and update dashboards
Run from the repository root. Use the same values file for rendering and installing:
helm lint helm/app-charts/signoz-dashboards \
-f my-dashboards-values.yaml
helm template my-dashboards helm/app-charts/signoz-dashboards \
-n <application-namespace> -f my-dashboards-values.yaml \
> /tmp/my-dashboards-rendered.yaml
helm upgrade --install my-dashboards helm/app-charts/signoz-dashboards \
-n <application-namespace> -f my-dashboards-values.yaml \
--timeout 15m
The ConfigMaps are ordinary Helm resources. A post-install,post-upgrade hook Job
imports them after they are created or updated. Helm waits for the Job and reports
an error if it fails. Successful and failed Jobs remain available for inspection;
the next install or upgrade replaces the previous hook Job.
To apply dashboard changes, edit or replace the JSON files and run the same
helm upgrade --install command again. This upgrades the dashboard release; it
does not upgrade the OBaaS platform or replace the SigNoz installation.
Replacement and removal behavior
On every install or upgrade, the importer deletes all existing dashboards whose titles exactly match the bundled titles, then creates dashboards from the JSON files. Other titles are preserved. Local JSON and duplicate titles are checked before deletion, but creation can still fail server-side if a payload is invalid. Replacement is not transactional; fix any failed import and rerun the upgrade.
A title match replaces the dashboard regardless of who created it. Avoid titles used by OBaaS system dashboards or other users. Replacement creates new dashboard IDs, which can break links, and overwrites UI edits to the matching dashboards.
If you remove a JSON file and upgrade the chart, Helm removes its ConfigMap, but the dashboard remains in SigNoz. Delete that dashboard manually in the SigNoz UI when you no longer need it. Changing a dashboard's title also leaves the old dashboard for manual cleanup.
Uninstalling the dashboard chart removes its ConfigMaps but leaves the imported dashboards in SigNoz. The retained hook Job can be deleted separately:
helm uninstall my-dashboards -n <application-namespace>
kubectl delete job my-dashboards-signoz-setup -n <application-namespace> \
--ignore-not-found
Verify and troubleshoot
helm status my-dashboards -n <application-namespace>
kubectl get jobs -n <application-namespace> \
-l app.kubernetes.io/instance=my-dashboards
kubectl logs -n <application-namespace> job/my-dashboards-signoz-setup \
-c signoz-setup
Open SigNoz and confirm your dashboard titles appear. If the Job does not start,
inspect its pod events and the signoz-setup container logs. Check image pulls,
SigNoz and ClickHouse health, the service URL, the credential Secret, and any
explicit orgID selection. HTTP 400 during
creation indicates the exported JSON needs checking against the deployed schema;
HTTP 401 or 403 indicates a credential or permission problem.