Skip to main content

Upgrade or remove monitoring

Upgrade​

Each Putki release publishes a new monitoring bundle. Upgrading keeps all recorded runs.

  1. Unzip the new bundle into a new folder and copy your .env into it.
  2. Run ./init-env.sh in the new folder: it adds any setting the new version requires and leaves yours alone. Compare with the new .env.example for new optional settings.
  3. From the old folder, stop the stack: docker compose -f docker-compose-monitoring.yml down. Without -v, so the data volumes stay.
  4. From the new folder, start it: docker compose -f docker-compose-monitoring.yml up -d. It finds the same data volumes, and logging-db-init brings the schema up to date.
  5. Re-run install-logging.sh against each project with the same --project-name. It lists the files it replaces and leaves your environment variables alone.

If you imported the dashboards into your own Grafana, import the new JSON files over the old ones. If you manage your own database, apply the new sql/init-logging.sql.

To 2026.12: Grafana's own database user​

From 2026.12, Grafana reads the logs with a read-only database user of its own instead of the user Hop writes with. Before 2026.12, anyone who could open a dashboard, including anonymous visitors with GRAFANA_ANONYMOUS=true, could send Grafana SQL of their own that ran as Hop's user, and so could change or delete the logs.

  • Add GRAFANA_DB_PASSWORD to your .env before step 4. The stack does not start without it.
  • The bundled database: logging-db-init creates the user, grafana_reader, on the first start.
  • Your own PostgreSQL: the user in LOGGING_DB_USER must be allowed to create users, or a database administrator creates it with sql/grafana-reader.sql (see Use your own PostgreSQL).
  • The full Putki stack: add GRAFANA_DB_PASSWORD to the stack's .env before upgrading. warehouse-db-init creates the user.
  • Your own Grafana: point the datasource at a read-only user (see Use your own Grafana).

To 2026.12: what changes on the dashboards​

  • A run is a top-level pipeline or workflow. The counters used to count top-level workflows only, so a pipeline run on its own was missing from them, and Failed counted runs still in progress. They now count both, and runs in progress have a counter of their own. Total runs is now Runs.
  • Rows written replaces Volume. Volume added up the rows of every row type, so a row was counted once per transform it passed. Rows written counts each pipeline's rows once, so expect lower numbers for the same days.
  • The tables are now Failed runs and All runs. Runs that finished with errors are failures too; they used to appear in neither table.
  • New: Name, Outcome and Runs filters, a Log search, and the pipelines and workflows a run started on the log detail page.
  • Alerts are on. Three alert rules are installed, and send nothing until you set a webhook: see Get alerts.
  • Single sign-on is available: see Sign in with Google, Microsoft or your SSO.
  • The bundle's Grafana starts through bin/putki-entrypoint.sh. Keep the bin folder next to the compose file.

From the original 2026.09 bundle​

The 2026.09 bundle was replaced on the release page with a corrected build of the same name. You have the original, or an earlier bundle, if the VERSION file in your folder has one line only. The corrected build adds a second line starting with built.

  • Keep your data: set the project name once. Older bundles named their data volumes after the folder they ran in. Before step 4, add that name to the new .env: the folder name in lower case, without dots, so putki-monitoring-2026.09 becomes

    COMPOSE_PROJECT_NAME=putki-monitoring-202609

    docker volume ls | grep monitoring shows the name if you are unsure. Newer bundles use a fixed name, so this is needed only once.

  • The bundled database is now the default. The new .env.example contains COMPOSE_PROFILES=logging-db. If you used your own PostgreSQL, leave that line out of your .env. If you started the stack with --profile logging-db, the line replaces the flag.

  • Run times are now stored with their time zone. The first start migrates log_object. Runs already recorded are read as UTC. If your Hop ran on local time, runs recorded before the upgrade keep their old offset; runs after it are exact.

  • The Marquez (OpenLineage) datasource is removed. Grafana deletes it on the first start.

Remove from a project​

Delete the five files the installer added:

rm -f  <project>/logging/pipeline-log.hpl <project>/logging/workflow-log.hpl
rm -rf <project>/metadata/pipeline-log <project>/metadata/workflow-log
rm -f  <project>/metadata/rdbms/logging.json

Runs stop being recorded at once; nothing else in the project changes. The LOGGING_* variables can stay in the environment file: nothing uses them without the pipelines.

Remove the stack​

docker compose -f docker-compose-monitoring.yml down       # keeps the data
docker compose -f docker-compose-monitoring.yml down -v    # also deletes all recorded runs