Tracing
ARK utilises OpenTelemetry to provide a comprehensive, end-to-end tracing solution across the platform. In the Ark Platform, tracing is integrated at both infrastructure and application levels to enable observability, performance monitoring, and troubleshooting.
All core services—including API gateways, backend modules, and connectors—are instrumented to automatically generate and propagate trace context using OpenTelemetry standards. This ensures that requests can be tracked as they traverse through different microservices, external connectors (such as Ultracs), and internal modules. Traces capture key metadata such as service names, operation names, timing, and error information, providing a unified view of distributed transactions.
The tracing implementation in the Ark Platform supports both local development and production deployments. In local environments, traces are processed using a SimpleSpanProcessor for immediate feedback, while production and non-local environments use a BatchSpanProcessor for efficient, high-throughput trace exporting. Trace data is emitted in the OpenTelemetry format, making it compatible with popular backends like Jaeger and Zipkin, as well as cloud-native observability platforms.
By adopting OpenTelemetry, Ark enables:
- Distributed tracing: End-to-end visibility into requests across all services and connectors.
- Performance analysis: Identification of bottlenecks and latency sources.
- Error correlation: Rapid root-cause analysis by correlating errors across service boundaries.
- Compliance and auditing: Centralized trace logs for auditing and compliance requirements.
This approach ensures that tracing is consistent, extensible, and easy to integrate with existing and future observability tools within the Ark ecosystem.
Configuration
Apps are configured using the following environment variables:
| Environment Variable | Description |
|---|---|
ENABLE_TRACING | Set to true to enable tracing. If not set or set to any other value, tracing will be disabled. |
APP_NAME | The name of your application. This will be used as the service name in the traces. |
It can also be configured using environment variables described in the OpenTelemetry Node SDK documentation.
Accessing traces
The location of traces will depend on the individual setup of the Ark platform within the organisation. Please refer to your organisation's documentation or contact your system administrator for details on where to find the traces. Traces will be available in the OpenTelemetry format, which can be ingested by various tracing backends such as Jaeger, Zipkin, or any other compatible system.
Adding tracing to requests
By default, all requests made to the Ark platform will automatically generate tracing headers. However, to help with traceability from the client application, it is recommended that the 'traceparent' header is added to inbound requests. This header should be in the format defined by the W3C Trace Context specification.