Observability

Supported versions: v2.1.0. and later.

Introduction

PactFlow On-Premises supports native OpenTelemetry (OTel) instrumentation to help you monitor and troubleshoot your on-premise instance. By enabling telemetry, you can use your existing observability tools to gain real-time visibility into application behavior, performance bottlenecks, and system health.

Telemetry includes key operational events, HTTP metrics, error traces, and performance signals from core PactFlow On-Premises services.

When you report issues to , we recommend attaching relevant trace data to your support tickets to assist in diagnosing complex problems.

Benefits

  • Proactive monitoring. Detect and resolve potential issues.

  • Faster debugging. Trace request paths and performance regressions across services.

  • Custom alerting. Integrate with your preferred observability stack to trigger alerts on thresholds or anomalies.

  • Open standard. Use any OpenTelemetry-compatible platform, for example, Dynatrace.

  • Support-ready diagnostics. Reduce turnaround time on support cases by sharing actionable telemetry traces.

Configuraton

To enable OpenTelemetry, follow these steps:

  1. Set the following environment variables in your deployment configuration:

    • OTEL_EXPORTER_OTLP_ENDPOINT: The OTLP (HTTP) endpoint you export spans to.

      Example: https://172.23.92.124:4318

    • OTEL_DEPLOYMENT_ENVIRONMENT: The name of the deployment environment (for example, production).

      Default: dev

    • OTEL_LOG_LEVEL: The log level for the OpenTelemetry SDK instrumentation (debug, info, and so on).

      Default: info

  2. Restart the application to apply the changes.

See the Application Configuration Guide for a complete list of configuration options.

Trace information

Traces follow standard naming rules when they exist, like those for HTTP or databases.

PactFlow On-Premises emits telemetry for:

  • HTTP request durations, routes, and status codes.

  • Internal service interactions (for example, contract publication, verification events).

  • SQL queries in the application.

  • Trace IDs (x-request-id) to support distributed correlation.

  • Error traces and response codes when applicable.

PactFlow On-Premises supports tracing information using the traceparent, tracestate, and x-request-id headers. This lets upstream gateways or load balancers help decide what to sample and keep tracing consistent across systems.

Note

OpenTelemetry instrumentation currently applies only to API requests. Tracing does not include browser-rendered UI interactions or background jobs, such as webhook executions or bi-directional contract comparisons.

Security and error handling

  • All sensitive fields (tokens, secrets, credentials) are excluded or redacted from trace payloads.

  • No Personally Identifiable Information (PII) or authorization headers are ever emitted.

  • Telemetry failures, such as network errors, do not interrupt the application flow. Trace data is emitted on a best-effort basis.

  • If set up incorrectly, PactFlow On-Premises uses a no-op exporter with logging internally only.

Application behavior

PactFlow On-Premises handles telemetry configuration safely and transparently.

Below you can see what to expect under different deployment conditions.

OpenTelemetry is enabled and correctly configured

  • Traces are sent to the specified OTLP over the HTTP endpoint.

  • Traces appear in your observability platform if routing is successful.

  • Internal operations (such as HTTP, database, and background jobs) are captured as spans.

OpenTelemetry is enabled, but misconfigured

  • No traces are sent to the collector.

  • You can check the OpenTelemetry SDK logs that indicate wrong setup or export errors.

  • Telemetry failures do not interfere with application execution.

  • PactFlow On-Premises switches to a no-op exporter and internally logs errors.

OpenTelemetry is not configured

  • No traces are emitted.

  • PactFlow On-Premises operates with no changes to behavior or performance.

  • No warnings or logs related to OpenTelemetry are generated.

Supported systems

  • OTLP over HTTP only.

  • Unauthenticated endpoints only. For example, local sidecars or internal collectors.

Note

PactFlow On-Premises does not currently support authentication headers.

Compatibility

OpenTelemetry is compatible with the following:

  • Bugsnag

  • Datadog

  • Dynatrace

  • Any OpenTelemetry-compliant backend platform.

Supported versions

PactFlow On-Premises supports OpenTelemetry v1.21+, by following the semantic conventions for HTTP, database, and background tasks.

In this section:
© 2025
Publication date: