Observability in Flowker

Configure Flowker telemetry and use its health endpoints and execution records to operate workflows.

Flowker can emit OpenTelemetry data for its HTTP and service operations. Telemetry is opt-in: enable it in the deployment, send it to your collector, and use the execution API for workflow-specific status and results.

Enable and export telemetry

---

Set these environment variables in the Flowker deployment:

ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://your-otlp-collector.example:4317

With telemetry enabled, Flowker initializes its telemetry instruments and exports through the configured OTLP endpoint. You do not add instrumentation to individual workflows, but the deployment must provide a reachable collector. Use an https:// endpoint for a remote collector; reserve a plaintext http:// endpoint for a collector that is local to the host or reachable only over an isolated network. Flowker does not provision Grafana dashboards, retention, or alert rules; those are decisions in your observability platform.

Check service health

---

Flowker exposes Kubernetes-compatible probes. GET /health is a liveness check: after its startup self-probe passes, it returns 200 healthy and deliberately does not call the database, cache, or downstream services. GET /readyz is the readiness check for dependencies and is the endpoint to use when you need to know whether Flowker can serve requests now.

Use your observability platform

---

Route the OTLP stream to the backend your platform operates, such as Grafana, and build dashboards and alerts there. Keep those dashboards separate from execution investigation: API request telemetry does not replace the execution record.

For an individual workflow run, use Get execution results to read its status, step results, and final output when present. A failed step can include an errorMessage; this response has no top-level error-details field.

How to interpret execution status

---

Each workflow execution in Flowker has a status that tells you where it stands.

Status	Meaning	What to do
pending	The execution has been created but has not started. In the normal execution path, Flowker changes it to running synchronously before responding; do not treat it as a scheduler queue.	—
running	Execution is in progress	Normal — monitor for completion
completed	All steps finished successfully	No action needed
failed	Execution finished with an error	Check stepResults for a failed step. A failure before any step runs has no step error in this response.

If you see a significant number of failed executions in a short period, collect their execution ids and error details before you escalate. A pattern is more actionable than an isolated failure.

When to involve engineering

---

Escalate to engineering when:

• GET /readyz reports a dependency as down
• the OTLP collector is unreachable or is rejecting the telemetry stream
• failed executions exceed the alert threshold your deployment defines and the cause is not clear
• Flowker is not processing new executions while readiness is successful

Share the execution ids, UTC timeframe, relevant API error payloads, and the /readyz response. If telemetry is enabled, include the collector or dashboard link as supporting evidence.