> ## 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).

By default only the first certificate in a certificate chain (i.e. the leaf certificate) is scraped. The `scrape_all_certs` option can be used to monitor all certificates in a file or all certificates presented by an endpoint.

```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 all certificates in a PEM bundle
      - file_path: /opt/app/ca-bundle.crt
        scrape_all_certs: true

      # 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. |
| `scrape_all_certs` | boolean | false | Option to scrape all certificates in the chain presented by an endpoint or in a file. |

### JKS Keystores

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

* **TrustedCertificateEntry** — the single certificate stored in the entry is used.
* **PrivateKeyEntry** — the first certificate in the chain (the leaf) is used by default. If `scrape_all_certs` is true, the other certificates in the chain are also scraped.

## 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, tlscheck.x509.fingerprint |

## Attributes

| Attribute Name | Description | Type | Values |
| - | - | - | - |
| `tlscheck.x509.cn` | The commonName in the subject of the certificate. | string | |
| `tlscheck.x509.fingerprint` | The SHA256 fingerprint 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-10-05*