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

# Tlscheck

> OpenTelemetry receiver for Tlscheck

# Tlscheck Receiver

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

**Available in:** `contrib`

**Maintainers:** [@atoulme](https://github.com/atoulme), [@michael-burt](https://github.com/michael-burt)

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

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-alpha-green)

## Overview

## Getting Started

By default, the TLS Check Receiver will emit a single metric, `tlscheck.time_left`, per target. This is measured in seconds until the date and time specified in the `NotAfter` field of the x.509 certificate. After certificate expiration, the metric value will be a negative integer measuring the time in seconds since expiry.

## Example Configuration

> **Note:** This receiver was renamed from `tlscheck` to `tls_check` to match the snake\_case naming convention.
> The deprecated component type `tlscheck` is still accepted as an alias and will log a deprecation warning.

Targets are configured as a remote endpoint accessed via TCP, a PEM-encoded certificate file stored locally on disk, or a Java-format keystore file (JKS or PKCS#12).

```yaml theme={null}
receivers:
  tls_check:
    targets:
      # Monitor a local PEM file (default when no file_format is set)
      - file_path: /etc/istio/certs/cert-chain.pem

      # Monitor a JKS keystore — format inferred from .jks extension
      - file_path: /opt/app/keystore.jks
        password: changeit

      # Monitor a PKCS#12 keystore — format inferred from .p12 extension
      - file_path: /opt/app/keystore.p12
        password: ${env:KEYSTORE_PASSWORD}

      # Explicit format override (e.g. a .ks file that is actually JKS)
      - file_path: /opt/app/keystore.ks
        file_format: jks
        password: changeit

      # Monitor a remote endpoint
      - endpoint: example.com:443

      # Monitor a local service with a custom timeout
      - endpoint: localhost:10901
        dialer:
          timeout: 15s
```

### Configuration Fields

| Field         | Type   | Default | Description                                                                                                                                                                                      |
| ------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `file_path`   | string |         | Path to a certificate file on disk. Mutually exclusive with `endpoint`.                                                                                                                          |
| `file_format` | string | `auto`  | Format of the certificate file. One of: `auto`, `pem`, `jks`, `pkcs12`. When `auto`, the format is inferred from the file extension (`.jks` → JKS; `.p12` / `.pfx` → PKCS#12; all others → PEM). |
| `password`    | string |         | Password for JKS or PKCS#12 keystores. The value is masked in logs and diagnostic output. Optional for unprotected JKS files.                                                                    |

### JKS Keystores

JKS files may contain multiple aliases. One `tlscheck.time_left` metric is emitted per leaf certificate found:

* **TrustedCertificateEntry** — the single certificate stored in the entry is used.
* **PrivateKeyEntry** — the first certificate in the chain (the leaf) is used.

## Certificate Verification

This component does not provide hostname, validity period, path, or CRL / OCSP verification on the certificate.

## Certificate File Validation

If a certificate file specified in the configuration does not exist or is unable to be opened, an error will be logged on each scrape cycle and the `otelcol_scraper_errored_metric_points` metric will be incremented. If you would like to monitor for the existence of specific certificate files on disk, consider using the [File Stats receiver](../filestatsreceiver/README.md).

## Metrics

Details about the metrics produced by this receiver can be found in [metadata.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/tlscheckreceiver/metadata.yaml).

## Metrics

| Metric Name            | Description                                                                                                                                                      | Unit | Type  | Attributes                                                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ----- | --------------------------------------------------------- |
| ✅ `tlscheck.time_left` | Time in seconds until certificate expiry, as specified by `NotAfter` field in the x.509 certificate. Negative values represent time in seconds since expiration. | s    | Gauge | tlscheck.x509.issuer, tlscheck.x509.cn, tlscheck.x509.san |

## Attributes

| Attribute Name         | Description                                       | Type   | Values |
| ---------------------- | ------------------------------------------------- | ------ | ------ |
| `tlscheck.x509.cn`     | The commonName in the subject of the certificate. | string |        |
| `tlscheck.x509.issuer` | The entity that issued the certificate.           | string |        |
| `tlscheck.x509.san`    | The Subject Alternative Name of the certificate.  | slice  |        |

## Resource Attributes

| Attribute Name    | Description                                                  | Type   | Enabled |
| ----------------- | ------------------------------------------------------------ | ------ | ------- |
| `tlscheck.target` | Endpoint or file path at which the certificate was accessed. | string | ✅       |

***

*Last generated: 2026-07-06*