Make OpenTelemetry tracing opt-in and handle exporter failures

[priscaenoch]

Problem

src/tracer.ts constructs a NodeSDK and calls sdk.start() unconditionally at import time, with OTLP_ENDPOINT defaulting to http://localhost:4318. This means every run of the service starts tracing and attempts to export spans to a local collector, even in development or CI where no collector exists, producing connection errors and overhead. There is no flag to disable it and no graceful shutdown.

What needs to be done

• Gate startup behind an explicit env flag (for example TRACING_ENABLED), off by default, or auto-disable when OTLP_ENDPOINT is unset.
• Wrap sdk.start() so exporter/connection errors are logged and do not crash or spam the process.
• Register a shutdown hook (sdk.shutdown()) on SIGTERM/SIGINT so spans flush cleanly.
• Document the tracing environment variables (OTLP_ENDPOINT, SERVICE_NAME, the new enable flag) in the README and .env.example.

Files

• src/tracer.ts
• .env.example, README.md

Acceptance deliverables

• Tracing is off by default and only starts when explicitly enabled or configured.
• A missing/unreachable collector does not produce repeated crashes or error spam.
• All CI checks pass; the change cannot be merged until CI is green.

Tests to pass

• Test: with tracing disabled/unconfigured, the SDK does not start.
• Test: an exporter initialization error is handled without throwing.

[DEV-DESIGN6]

I’d like to work on this task because it’s a focused reliability improvement that prevents unnecessary tracing overhead and connection errors in development and CI.

I’ll update src/tracer.ts so OpenTelemetry tracing is disabled by default and only starts when explicitly enabled through a clear environment flag such as TRACING_ENABLED, while keeping OTLP_ENDPOINT configurable. I’ll also make startup failures non-fatal so an unavailable collector cannot crash the service or repeatedly spam the logs.

For graceful shutdown, I’ll register SIGTERM and SIGINT handlers that call sdk.shutdown() and allow pending spans to flush cleanly before the process exits. I’ll update .env.example and the README with the tracing configuration and expected behavior.

I’ll also add or update tests to verify that the SDK does not start when tracing is disabled or unconfigured, and that exporter initialization errors are handled without throwing. Finally, I’ll run the project’s existing CI checks to ensure the implementation is clean and all checks pass.

[marvel6828]

I’d like to take on this issue and make the tracing setup more reliable without changing the existing application behavior unnecessarily.

I’ll update src/tracer.ts to ensure tracing is disabled by default and only starts when explicitly enabled through a TRACING_ENABLED flag or when a valid OTLP_ENDPOINT is configured. I’ll also handle SDK/exporter startup errors gracefully so an unavailable collector never crashes the application or creates repeated error noise.

I’ll add graceful shutdown handling for SIGTERM and SIGINT using sdk.shutdown() to ensure pending spans are flushed properly. I’ll also update .env.example and the README with clear documentation for TRACING_ENABLED, OTLP_ENDPOINT, and SERVICE_NAME.

For testing, I’ll cover both the disabled/unconfigured case and exporter initialization failures, ensuring the SDK does not start unnecessarily and errors are handled without throwing. I’ll finish by running the full CI/test suite and making sure all checks pass.

[grantfox-oss]

🦊 GrantFox — @marvel6828 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #43)
2. Your PR will be reviewed by the octraban maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@marvel6828's PR #59 was approved and merged by @priscaenoch.

🏆 @marvel6828: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (48 total points). Track your full progress on GrantFox.

👏 Great work, @marvel6828! Keep contributing to octraban.