Execution information reference

Applies toApache Hop 2.20Putki 2026.12

Bundle contents

Path	What it is
docker-compose-neo4j.yml	Neo4j, the optional read-only copy, and the backup and restore one-shots
.env.example	Template for .env, the only file you edit
init-env.sh	Writes .env from .env.example and fills in the required settings: asks, or --generate makes up the passwords. Never changes a value already set
install-execution-logging.sh	Configures a Hop project to record into Neo4j
backup.sh, restore.sh	Dump the graph to backups/, load it back
refresh-readonly.sh	Fills the read-only copy from a fresh backup
backups/	Where the dumps go
VERSION	The bundle version, for support requests

.env settings

Setting	Default	Meaning
NEO4J_PASSWORD	required	Password of the neo4j user, which Hop writes with
NEO4J_HTTP_PORT	7474	Host port of the Neo4j Browser
NEO4J_BOLT_PORT	7687	Host port Hop writes to
NEO4J_BIND_ADDR	127.0.0.1	Interface the ports listen on
NEO4J_HTTP_ADVERTISED, NEO4J_BOLT_ADVERTISED	localhost:7474, localhost:7687	Addresses the Browser connects back to
NEO4J_HEAP_MAX	1G	Neo4j's maximum heap
GRAPH_NETWORK	putki-graph-logging	Docker network; a Hop container on it reaches neo4j:7687
NEO4J_READONLY_PASSWORD		Password of the read-only copy. Required by refresh-readonly.sh
NEO4J_READONLY_HTTP_PORT, NEO4J_READONLY_BOLT_PORT	7475, 7688	Host ports of the read-only copy
NEO4J_READONLY_BOLT_ADVERTISED	localhost:7688	Bolt address the copy's Browser connects back to

install-execution-logging.sh options

Option	Default	Meaning
--project-home DIR		The Hop project to configure. Without it, every project under $PUTKI_PROJECTS_ROOT (the Putki stack's mode)
--neo4j-host HOST	neo4j	Where Hop reaches Neo4j. localhost for Hop on the same machine
--neo4j-port PORT	7687	Bolt port
--neo4j-user USER	neo4j
--neo4j-password PASS	required
--neo4j-database NAME	neo4j
--neo4j-tls		Encrypted Bolt, trusting the server's certificate
--connection-name NAME	neo4j	Name of the graph database connection
--location-name NAME	putki-neo4j	Name of the execution information location

With PUTKI_NEO4J_EXECUTION_LOGGING=false in its environment, the installer removes what it installed instead.

It writes into the project:

File	Role
metadata/graph-database-connection/neo4j.json	The connection, of type Neo4j. Every setting is a ${NEO4J_*} variable
metadata/execution-info-location/putki-neo4j.json	The execution information location, of type graph database, using that connection
metadata/*-run-configuration/*.json	executionInfoLocationName set to putki-neo4j where it was empty, local or local-audit
environments/*.json	The variables below

Hop variables

Variable	Meaning
NEO4J_HOSTNAME, NEO4J_PORT	Where Neo4j is
NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_DATABASE	How to sign in, and which database
NEO4J_BOLT_TLS	true for encrypted Bolt, trusting the certificate
HOP_GRAPH_LOGGING_CONNECTION	Name of the connection the execution graph is written to; empty or - switches it off

Graph

Element	What it is
(:Execution) with a filename	A run of a pipeline, workflow or transform, from the execution information location: name, executionType, statusDescription, failed, registrationDate, executionStartDate, executionEndDate, loggingText
(:Execution)-[:EXECUTES]->(:Execution)	A run started another
(:Execution)-[:HAS_METRIC]->(:ExecutionMetric)	A pipeline run's figures per transform: name (the transform), metricKey (Read, Written, Errors, Duration, ...), metricValue
(:Workflow), (:Pipeline), (:Action), (:Transform)	The execution graph: ACTION_OF_WORKFLOW, TRANSFORM_OF_PIPELINE, PRECEDES
(:Execution) without a filename	A run, from the execution graph: status, durationMs, linesRead, linesWritten, errors

Queries

The latest runs:

MATCH (e:Execution)
WHERE e.filename IS NOT NULL AND e.executionType IN ["Pipeline", "Workflow"]
RETURN e.name, e.executionType, e.statusDescription, e.failed, e.registrationDate
ORDER BY e.registrationDate DESC LIMIT 25

Failed runs and their logs:

MATCH (e:Execution)
WHERE e.filename IS NOT NULL AND e.failed = true
RETURN e.name, e.registrationDate, e.loggingText
ORDER BY e.registrationDate DESC LIMIT 10

Rows per transform of a pipeline's runs:

MATCH (:Execution {executionType: "Pipeline", name: "load-orders"})-[:HAS_METRIC]->(m:ExecutionMetric)
RETURN m.name, m.metricKey, m.metricValue

The transforms of each pipeline:

MATCH (p:Pipeline)<-[:TRANSFORM_OF_PIPELINE]-(t:Transform)
RETURN p.name, collect(t.name)