> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Healthcheck

> OpenTelemetry extension for Healthcheck

# Healthcheck Extension

![Status](https://img.shields.io/badge/status-alpha-red)

**Available in:** `core`, `contrib`, `k8s`

**Maintainers:** [@evan-bradley](https://github.com/evan-bradley), [@mwear](https://github.com/mwear)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension)

## Overview

> ℹ️ **Migration Notice** ℹ️
>
> This extension is migrating to use component status reporting for health checks
> while maintaining full backward compatibility. See the [Backward Compatibility](#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 [https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/11780](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/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`](https://github.com/open-telemetry/opentelemetry-collector/tree/main/config/confighttp). See our [security best practices doc](https://opentelemetry.io/docs/security/config-best-practices/#protect-against-denial-of-service-attacks) 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:

```yaml theme={null}
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](../../internal/healthcheck/internal/http/config.go#L24)
with detailed sample configurations in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension/testdata/config.yaml).

## Backward Compatibility

[Linked issue](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/42256).

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:

```bash theme={null}

--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

## Configuration

### Example Configuration

```yaml theme={null}
health_check:
health_check/1:
  endpoint: "localhost:13"
  tls:
    ca_file: "/path/to/ca"
    key_file: "/path/to/key"
    cert_file: "/path/to/cert"
  check_collector_pipeline:
    enabled: false
    interval: "5m"
    exporter_failure_threshold: 5
health_check/missingendpoint:
  endpoint: ""
  check_collector_pipeline:
    enabled: false
    interval: "5m"
    exporter_failure_threshold: 5
health_check/invalidthreshold:
  endpoint: "localhost:13"
  check_collector_pipeline:
    enabled: false
    interval: "5m"
    exporter_failure_threshold: -1
health_check/invalidpath:
  endpoint: "localhost:13"
  path: "invalid"
  check_collector_pipeline:
    enabled: false
    interval: "5m"
    exporter_failure_threshold: 5
health_check/response-body:
  response_body:
    healthy: I'm OK
    unhealthy: I'm not well
health_check/v2-http-only:
  http:
    endpoint: "localhost:13133"
    status:
      enabled: true
      path: "/status"
    config:
      enabled: false
      path: "/config"
health_check/v2-grpc-only:
  grpc:
    endpoint: "localhost:13132"
    transport: tcp
health_check/v2-both-protocols:
  http:
    endpoint: "localhost:13133"
    status:
      enabled: true
      path: "/status"
    config:
      enabled: true
      path: "/config"
  grpc:
    endpoint: "localhost:13132"
    transport: tcp
  component_health:
    include_permanent_errors: true
    include_recoverable_errors: true
    recovery_duration: 1m
health_check/v2-missing-protocol:
health_check/v2-http-missing-endpoint:
  http:
    endpoint: ""
health_check/v2-grpc-missing-endpoint:
  grpc:
    endpoint: ""
health_check/v2-invalid-status-path:
  http:
    endpoint: "localhost:13133"
    status:
      enabled: true
      path: "invalid"
health_check/v2-invalid-config-path:
  http:
    endpoint: "localhost:13133"
    status:
      enabled: true
      path: "/status"
    config:
      enabled: true
      path: "invalid"
```

***

*Last generated: 2026-07-06*