Skip to main content

​
Tlscheck Receiver

Status Available in: contrib Maintainers: @atoulme, @michael-burt Source: opentelemetry-collector-contrib

​
Supported Telemetry

Metrics

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

FieldTypeDefaultDescription
file_pathstringPath to a certificate file on disk. Mutually exclusive with endpoint.
file_formatstringautoFormat 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).
passwordstringPassword 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.

​
Metrics

Details about the metrics produced by this receiver can be found in metadata.yaml.

​
Metrics

Metric NameDescriptionUnitTypeAttributes
✅ tlscheck.time_leftTime in seconds until certificate expiry, as specified by NotAfter field in the x.509 certificate. Negative values represent time in seconds since expiration.sGaugetlscheck.x509.issuer, tlscheck.x509.cn, tlscheck.x509.san

​
Attributes

Attribute NameDescriptionTypeValues
tlscheck.x509.cnThe commonName in the subject of the certificate.string
tlscheck.x509.issuerThe entity that issued the certificate.string
tlscheck.x509.sanThe Subject Alternative Name of the certificate.slice

​
Resource Attributes

Attribute NameDescriptionTypeEnabled
tlscheck.targetEndpoint or file path at which the certificate was accessed.string✅
Last generated: 2026-04-13