Skip to main content

Logging

The SDK includes a built-in logger (OneAPILogger) that traces requests, responses, retries, and token refresh operations. Logging is disabled by default. You can enable it by passing a LoggerConfig object to your Session. Sensitive headers and credential fields are automatically redacted.

Quick Start

To enable basic logging for a session, create a Config object with an embedded LoggerConfig and pass it to zssdk.Session:

from zssdk.zscore.config import Config, LoggerConfig
import zssdk

config = Config(
    logger_config=LoggerConfig(
        enabled=True,
        verbose=False,
        logging_format="json",
        log_to_file=True,
        log_file_path="/var/log/zssdk.log",
    )
)
session = zssdk.Session(config=config, profile_name="beta")

Log Format

The logging_format setting controls how log lines are formatted. It accepts three values:

FormatOutputUse case
basicHuman-readable lines: %(asctime)s - %(name)s - %(module)s - %(levelname)s - %(message)sLocal development
jsonOne structured record per lineProduction; log aggregators (Loki, Elastic, and Splunk)
customUser-provided logging.FormatterSpecialized environments; programmatic only

Example JSON Log Line:

{"timestamp":"2026-04-22T14:02:31Z","level":"INFO","service":"zia","operation":"ListFirewallFilteringRules","duration_ms":142,"status_code":200,"session_id":"abc-123","request_id":"def-456"}

Custom Formatter​

Use a custom formatter when you need log lines to match an existing logging standard or ingest pipeline. Custom formatting is available only via LoggerConfig and cannot be configured via environment variables.

import logging
from zssdk.zscore.config import Config, LoggerConfig

fmt = logging.Formatter("%(levelname)s | %(service)s.%(operation)s | %(message)s")
config = Config(
    logger_config=LoggerConfig(
        enabled=True,
        logging_format="custom",
        custom_formatter=fmt,
    )
)

Verbose Logging

Verbose mode is useful when you need deep diagnostics, including payloads and headers, for debugging issues with API calls. Setting verbose=True includes request and response bodies and full header dumps in the logs (with credentials still redacted). Avoid enabling this in production because payloads can be large and increase overhead and storage usage.

config = Config(logger_config=LoggerConfig(enabled=True, verbose=True))

Sensitive Data Redaction

The logger automatically redacts common credential-bearing fields before writing logs, so you can safely enable logging without manual scrubbing. Specifically, it redacts:

  • Authorization request headers
  • client_secret, private_key, AND cert_file_path values in Config
  • Response bodies that contain token or credential-like structures

Redaction runs before formatting and output, regardless of the selected log format.

Request and Session Tracing

Every session and every request is assigned a UUID that appears in log entries:

  • session_id — Identifies the SDK session
  • request_id — Identifies the individual API call

In JSON format, these appear as separate fields; in basic format, they are appended to the log message. Use these identifiers to correlate SDK activity with upstream API logs and your application’s traces.

{"level":"INFO","session_id":"abc-123","request_id":"def-456","operation":"ListAdminRoles","duration_ms":89}

Production Recommendations

  • Use logging_format="json" so logs can be parsed reliably by aggregators.
  • Keep verbose=False to avoid logging large request and response bodies, reducing performance overhead and log-storage usage.
  • Rotate log files with logrotate or an equivalent tool; the SDK does not perform log rotation.
  • Include both session_id and request_id in your application's log-correlation fields.
  • If you run multiple sessions per process (multi-tenant and multi-cloud), capture the session ID at session creation so you can correlate back to the relevant configuration profile.

Related