Datadog Observability
Relevant source files
The following files were used as context for generating this wiki page:
The Datadog Observability system in the Care Ops Frontend project provides comprehensive monitoring, logging, and Real User Monitoring (RUM) capabilities. It is designed as a shared infrastructure layer utilized by both the main application and specialized sub-packages, such as the forms runtime. The primary purpose is to capture client-side performance metrics, user sessions, and application errors to ensure high availability and facilitate rapid debugging.
The implementation relies on the @datadog/browser-logs and @datadog/browser-rum libraries, which are wrapped in internal helpers to provide a consistent interface across different deployment environments and services.
Architecture and Integration
The observability architecture is structured as a series of hierarchical wrappers. At the base, @roundingwell/care-ops-datadog provides low-level initialization helpers. Above this, service-specific modules configure these helpers based on application state and environmental flags.
Main Application Integration
In the main application, the observability layer is managed via src/js/datadog.js. It uses environmental guards to ensure monitoring is only active in appropriate contexts.
The initialization process for the main frontend service defaults to the service name app-frontend.
Sources: src/js/datadog.js:6-14
Forms Service Integration
The forms runtime (@roundingwell/care-ops-forms) implements its own observability initialization logic, allowing it to function as an independent service (typically customer-forms) with distinct logging and RUM configurations.
Core Components and Functions
The system is composed of shared packages and utility functions that manage the lifecycle of Datadog agents.
Key Functions
| Function | Source | Description |
|---|---|---|
initDataDog | src/js/datadog.js | Main entry point for initializing logs and RUM for the frontend app. |
initFormServices | packages/care-ops-forms/index.js | Initializes config, posts version, and sets up Datadog for forms. |
initLogs | packages/care-ops-datadog | Wrapper for @datadog/browser-logs initialization. |
initRum | packages/care-ops-datadog | Wrapper for @datadog/browser-rum initialization. |
setUser | src/js/datadog.js | Associates the current user session with Datadog telemetry. |
addError | packages/care-ops-datadog | Manually logs an error to the Datadog platform. |
Sources: src/js/datadog.js:1-20, packages/care-ops-forms/index.js:79-91
Package Dependencies
The observability stack is distributed across the following workspace packages:
@roundingwell/care-ops-datadog: Contains the core logic and direct dependencies on Datadog browser SDKs (^6.2.1).@roundingwell/care-ops-config: Provides the options and client tokens required for initialization.@roundingwell/care-ops-forms: Consumers of the observability helpers for form-specific tracking.
Sources: packages/care-ops-datadog/package.json:11-14, packages/care-ops-forms/package.json:13-16
Operational Logic
Environment Constraints
Initialization is strictly controlled by environment variables. The main application will not initialize Datadog if _PRODUCTION_ is false or if _TEST_ is true. Similarly, the forms service skips initialization if the hostname is localhost.
Sources: src/js/datadog.js:7-8, packages/care-ops-forms/index.js:52
Specialized Handling (PDF Printing)
The observability logic includes a specific branch for PDF generation requests. When a form is requested as a PDF (?pdf=true), the system initializes logging but explicitly bypasses RUM initialization and the startRum() call to avoid unnecessary overhead in headless browser environments used for printing.
Sources: packages/care-ops-forms/index.js:19-21, packages/care-ops-forms/index.js:63-65
Conclusion
Datadog Observability in the Care Ops Frontend provides a modular and guarded approach to application monitoring. By encapsulating Datadog SDKs within the care-ops-datadog package and centralizing configuration through care-ops-config, the project ensures that telemetry is consistently gathered across different sub-systems while maintaining strict control over environmental deployment and performance impacts.