This is unreleased documentation for SBOM Scanner 0.13-dev.

OpenTelemetry

SBOM Scanner exports traces and metrics with OpenTelemetry, over OTLP/gRPC. Telemetry export is off by default. When you enable it, one scan produces one trace across all the components. The trace starts at the admission webhook and ends at the SQL statements of the storage component. The metrics include scan counts, stage durations, and the resource usage of each replica.

The full list of spans and metrics is in the OpenTelemetry Reference.

The controller also serves its metrics on the standard controller-runtime Prometheus endpoint. Telemetry export does not change this endpoint.

Prerequisites

  • An OTLP/gRPC endpoint that receives the telemetry. This is usually an OpenTelemetry Collector in the cluster. An OTLP-compatible backend also works.

  • A TLS server certificate for the endpoint, and a client certificate for SBOM Scanner. You can create the certificates with cert-manager.

Enable telemetry export

Set the otel.endpoint value to the URL of your OTLP endpoint:

helm upgrade sbomscanner ./chart \
  --set otel.endpoint=https://otel-collector.telemetry.svc.cluster.local:4317

The URL scheme controls the connection security. An https:// URL makes the components connect with TLS.

Do not use an http:// URL in production. An http:// URL sends the telemetry as plaintext on the network.

Configure mTLS

Two values configure the TLS certificates. Both secrets must exist in the namespace where SBOM Scanner is installed.

  • otel.caSecretName names a secret that contains a ca.crt key. The components use this CA certificate to verify the server certificate of the endpoint.

  • otel.clientCertificateSecretName names a secret that contains tls.crt and tls.key keys. The components use this certificate to authenticate to the endpoint (mTLS).

Create the certificates with cert-manager

This example creates a client certificate from an existing cert-manager issuer. The certificate secret also contains the ca.crt key of the issuer. For this reason, one secret can serve both values.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: sbomscanner-otel-client
  namespace: sbomscanner
spec:
  secretName: sbomscanner-otel-client
  commonName: sbomscanner
  usages:
    - client auth
  issuerRef:
    kind: ClusterIssuer
    name: my-ca-issuer

The OTLP endpoint must present a server certificate from the same issuer. It must also require client certificates from this issuer. For an OpenTelemetry Collector, set cert_file, key_file, and client_ca_file on the OTLP receiver.

Install with mTLS

Set all three values:

helm upgrade sbomscanner ./chart \
  --set otel.endpoint=https://otel-collector.telemetry.svc.cluster.local:4317 \
  --set otel.caSecretName=sbomscanner-otel-client \
  --set otel.clientCertificateSecretName=sbomscanner-otel-client

The chart mounts the secrets into the components. Then the components connect to the endpoint with TLS and a client certificate.

Histograms

The components export histograms as exponential histograms. Exponential histograms adapt their bucket resolution to the recorded values. Prometheus stores them as native histograms.

Some backends do not support exponential histograms. If your backend does not support them, convert the histograms in the collector. The transform processor converts them to explicit histograms:

processors:
  transform:
    metric_statements:
      - context: metric
        statements:
          - convert_exponential_histogram_to_histogram("midpoint", [0.05, 0.1, 0.5, 1, 5, 30, 120])

Example dashboard

The SBOM Scanner repository contains an example Grafana dashboard at examples/dashboards/sbomscanner.json. The dashboard shows the scan counters, the stage durations, the storage metrics, and the resource usage of each replica. The latency panels show exemplars. An exemplar connects one point on a latency panel to the trace that produced it.