Class Logs

constructor

• new Logs(
      opts?: LoggingOptions,
      shared?: {
          auditDest: TrackedDestination;
          context: LogContext;
          failClosed: boolean;
          opDest: TrackedDestination;
          opLogger: Logger;
          product: OcsfProduct;
          state: { auditOpenFailed: boolean };
          writeAudit: (event: Record<string, unknown>) => void;
      },
  ): Logs

  Parameters

  • Optionalopts: LoggingOptions = {}

    logging options

  • Optionalshared: {
        auditDest: TrackedDestination;
        context: LogContext;
        failClosed: boolean;
        opDest: TrackedDestination;
        opLogger: Logger;
        product: OcsfProduct;
        state: { auditOpenFailed: boolean };
        writeAudit: (event: Record<string, unknown>) => void;
    }

    internal: shared state for child loggers

  Returns Logs

ReadonlyfailClosed

auditHealthy

• get auditHealthy(): boolean

  Whether the audit destination has failed at least once.

  Returns boolean

  true when healthy

ctx

• get ctx(): LogContext

  Context fields attached to this logger.

  Returns LogContext

audit

• audit(
      event:
          | "authentication.mode_configured"
          | "authentication.succeeded"
          | "authentication.failed"
          | "authentication.token_in_url_rejected"
          | "upstream.token.issue"
          | "upstream.token.issue_failed"
          | "upstream.token.refresh"
          | "upstream.token.refresh_failed"
          | "upstream.token.invalidated"
          | "authorization.policy_loaded"
          | "authorization.allowed"
          | "authorization.denied"
          | "credential.provider.configured"
          | "credential.config_invalid"
          | "credential.lookup_failed"
          | "execution.policy.applied"
          | "execution.requested"
          | "execution.import_denied"
          | "execution.resource_limit"
          | "execution.capability_denied"
          | "execution.timeout"
          | "executor.terminated"
          | "execution.boundary_violation"
          | "network.destination_denied"
          | "network.redirect_denied"
          | "transport.host_rejected"
          | "transport.origin_rejected"
          | "security.config_invalid"
          | "security.unauthenticated_nonloopback_refused",
      outcome: AuditOutcome,
      fields?: Record<string, unknown>,
      level?: AuditLevel,
  ): boolean

  Record a security audit event as an OCSF event. Audit records bypass the operational level filter and are never sampled.

  Parameters

  • event:
        | "authentication.mode_configured"
        | "authentication.succeeded"
        | "authentication.failed"
        | "authentication.token_in_url_rejected"
        | "upstream.token.issue"
        | "upstream.token.issue_failed"
        | "upstream.token.refresh"
        | "upstream.token.refresh_failed"
        | "upstream.token.invalidated"
        | "authorization.policy_loaded"
        | "authorization.allowed"
        | "authorization.denied"
        | "credential.provider.configured"
        | "credential.config_invalid"
        | "credential.lookup_failed"
        | "execution.policy.applied"
        | "execution.requested"
        | "execution.import_denied"
        | "execution.resource_limit"
        | "execution.capability_denied"
        | "execution.timeout"
        | "executor.terminated"
        | "execution.boundary_violation"
        | "network.destination_denied"
        | "network.redirect_denied"
        | "transport.host_rejected"
        | "transport.origin_rejected"
        | "security.config_invalid"
        | "security.unauthenticated_nonloopback_refused"

    stable event name, e.g. "authorization.denied"

  • outcome: AuditOutcome

    "success", "failure", "allowed", "denied", ...

  • Optionalfields: Record<string, unknown> = {}

    identifiers, policy ids and reason codes only

  • Optionallevel: AuditLevel = "info"

    "info" (default), "warn" or "error"

  Returns boolean

  whether the record was written successfully

auditBlocksExecution

• auditBlocksExecution(): boolean

  Whether execution must be refused because auditing is required (fail-closed) but unavailable.

  Returns boolean

  true when execution must be refused

child

• child(ctx: LogContext): Logs

  Create a child logger with additional context fields.

  Parameters

  • ctx: LogContext

    context fields such as requestId

  Returns Logs

  child logger sharing destinations

flush

• flush(): void

  Flush destinations, e.g. on graceful shutdown.

  Returns void

op

• op(
      level: Level,
      event: string,
      fields?: Record<string, unknown>,
      message?: string,
  ): void

  Record an operational event as an OpenTelemetry log record.

  Fields are redacted and bounded, then named by the OpenTelemetry semantic conventions (see toOtelAttributes).

  Parameters

  • level: Level

    pino level

  • event: string

    stable event name, e.g. "server.ready"

  • Optionalfields: Record<string, unknown> = {}

    structured context (never secrets or bodies)

  • Optionalmessage: string

    optional human message (default: the event)

  Returns void