Skip to main content

Logs

Overview​

The SPIRL agent outputs logs in JSON format to help monitor and troubleshoot agent operations.

Loggers​

agent.endpoints​

Logs for the endpoints component that serves the SPIFFE Workload API and Envoy SDS (Secret Discovery Service) API.

  • Requests from workloads for SVIDs and trust bundles
  • Unix domain socket listener management
  • gRPC servers for the Workload API

agent.sessionClient​

Logs for the SessionClient that manages the authenticated session between the agent and the SPIRL signer.

  • Authentication
  • Connection management and gRPC communication with SPIRL endpoints
  • Connection lifecycle, retries, and TLS configuration

agent.bundleRefresher​

Logs for the bundle refresher that periodically syncs trust bundles from the signer.

  • Updating the local bundle cache with added, updated, or removed bundles
  • Retries on failures

Understanding Memory & CPU Usage​

By default, the SPIRL agent logs the memory and CPU usage of its host once every second.

  • 90%: If either the memory or CPU pass this level, an ERROR log will be produced.
  • 80%: If either the memory or CPU pass this level, a WARN log will be produced.
  • Below 80%: If both the memory and CPU are under this level, a DEBUG log will be produced.

Limitations: When running inside of K8s containers specifically, CPU usage may be underrepresented. If this impacts you, please inform us so we can consider an improvement.

Sample logs:

{"level":"info","ts":1764183278.8113222,"msg":"starting resource limit logger"}
{"level":"debug","ts":1764183279.811754,"msg":"current memory percent used: 61%, current cpu percent used: 10%"}
{"level":"warn","ts":1764183280.812596,"msg":"current memory percent used: 82%, current cpu percent used: 9%"}
{"level":"debug","ts":1764183281.8117352,"msg":"current memory percent used: 61%, current cpu percent used: 5%"}
{"level":"debug","ts":1764183282.812567,"msg":"current memory percent used: 61%, current cpu percent used: 6%"}
{"level":"debug","ts":1764183283.812664,"msg":"current memory percent used: 61%, current cpu percent used: 4%"}
{"level":"debug","ts":1764183284.812612,"msg":"current memory percent used: 61%, current cpu percent used: 6%"}
{"level":"error","ts":1764183285.8126469,"msg":"current memory percent used: 93%, current cpu percent used: 9%"}
{"level":"debug","ts":1764183286.812633,"msg":"current memory percent used: 61%, current cpu percent used: 14%"}
{"level":"debug","ts":1764183287.812567,"msg":"current memory percent used: 61%, current cpu percent used: 5%"}
{"level":"debug","ts":1764183288.812623,"msg":"current memory percent used: 61%, current cpu percent used: 4%"}
{"level":"info","ts":1764183288.8126678,"msg":"stopping resource limit logger"}

If you suspect the agent may have failed due to encountering memory or CPU limits, searching the logs at an ERROR level will output any related messages.

To disable these logs due to logging cost concerns, use the following setting:

agent:
  env:
    - name: SPIRL_SILENCE_USAGE_LOGS
      value: "true"

Debug Logs​

Debug logs can be enabled for more detailed information about agent operations.

Note: The agent must be restarted for the log level change to take effect.

Enabling Debug Logs​

For Kubernetes Deployments​

Add the following environment variable to your agent configuration:

agent:
  env:
    - name: SPIRL_LOG_DEBUG
      value: "true"

For Other Environments​

Set the environment variable before starting the agent:

export SPIRL_LOG_DEBUG=true

For Node Groups​

Add the Environment field as below to the service file located at /lib/systemd/system/spirl-agent.service:

[Unit]
Description=SPIRL Agent
After=network.target

[Service]
RuntimeDirectory=spirl/sockets
Type=simple
ExecStart=/usr/sbin/spirl-agent --config-file-path /etc/spirl/agent-config.yaml
Environment="SPIRL_LOG_DEBUG=true"

[Install]
WantedBy=multi-user.target

After modifying the service file, reload the systemd configuration and restart the service:

sudo systemctl daemon-reload
sudo systemctl restart spirl-agent.service

What to Expect​

When debug logging is enabled, log volume will increase by approximately 25%. You'll see detailed information about:

  • Agent startup and authentication - Logs about how the agent authenticates with the signer
  • Workload API requests - Detailed logs for each workload request including SPIFFE ID validation, SVID minting operations, and stream management for X509 and JWT credentials
  • Attestation and rotation events - Information about when the agent attests or re-attests, and when SVIDs are rotated due to expiration, attribute changes, or validation errors
  • Workload discovery - Container and pod detection logs from Kubernetes, Docker, and other attestors, including pod listings, container inspections, and PID enumeration
  • JWT operations - JWT validation, claim processing, and bundle management
  • Bundle synchronization - Trust bundle refresh operations and updates

These debug logs help trace the complete lifecycle of SVID issuance, from workload detection through attestation to credential delivery.