healthcheckextension

Health Check Extension

Status
Stability	alpha
Distributions	core, contrib, k8s
Issues
Code coverage
Code Owners	@evan-bradley | Seeking more code owners!

ℹ️ Migration Notice ℹ️

This extension is migrating to use component status reporting for health checks while maintaining full backward compatibility. See the Backward Compatibility section for details about feature gates and migration options.

⚠️⚠️⚠️ Warning ⚠️⚠️⚠️

The check_collector_pipeline feature of this extension is not working as expected. It is recommended to not use the feature. The work to add a new version of the healthcheck extension that relies on individual component status is in progress. To avoid breaking backwards compatibility, the configuration will not be changed until the new extension is available as a replacement for this one. See #11780 for more details.

Health Check extension enables an HTTP url that can be probed to check the status of the OpenTelemetry Collector. This extension can be used as a liveness and/or readiness probe on Kubernetes.

The following settings are available:

• endpoint (default = localhost:13133): Address to publish the health check status. You can review the full list of ServerConfig. See our security best practices doc to understand how to set the endpoint in different environments.
• path (default = "/"): Specifies the path to be configured for the health check server.
• response_body (default = {}): Specifies a static body that overrides the default response returned by the health check service.
  • response_body::healthy: Specifies the body returned when service is healthy.
  • response_body::unhealthy: Specifies the body returned when service is unhealthy.

Example:

extensions:
  health_check:
  health_check/1:
    endpoint: "localhost:13"
    tls:
      ca_file: "/path/to/ca.crt"
      cert_file: "/path/to/cert.crt"
      key_file: "/path/to/key.key"
    path: "/health/status"
    response_body:
      healthy: I'm good
      unhealthy: I'm bad!

The full list of settings exposed for this exporter is documented in LegacyConfig in config.go with detailed sample configurations in testdata/config.yaml.

Backward Compatibility

Linked issue.

This extension maintains full backward compatibility with the original Ready/NotReady behavior by keeping the legacy implementation active unless a feature gate is enabled.

Feature Gate: extension.healthcheck.useComponentStatus

• Default: Disabled (false)
• Purpose: Switches the extension to the shared healthcheck implementation that reports status from component events
• When enabled: Health status is determined by component status events (v2 behavior)
• When disabled: Ready/NotReady calls directly control health endpoint status using the legacy implementation

Usage

To use the new event-driven behavior:

# Set the feature gate to true
--feature-gates=+extension.healthcheck.useComponentStatus

Migration Timeline

1. Current: Compatibility wrapper enabled by default - no breaking changes.
2. Future: Feature gate will be removed, compatibility wrapper will be permanently disabled.
3. Recommended: Test your setup with the feature gate enabled to prepare for future versions.

Ready/NotReady Behavior

Legacy Implementation (Default)

• Ready() → Health endpoint returns 200 OK
• NotReady() → Health endpoint returns 503 Service Unavailable
• Behavior identical to original extension

Shared Healthcheck Implementation (Feature gate enabled)

• Ready()/NotReady() → Used for pipeline lifecycle only
• Health status determined by component status events
• Behavior similar to healthcheckv2extension