Logging Behavior

Version: v1.1.0
This page documents behavior guaranteed in TealTiger v1.1.0. TealTiger emits two types of operational outputs: audit events for compliance evidence, and logs for debugging and monitoring. Both are structured and redaction-safe by default.

Logs vs Audit Events

Think of them like this:

Audit events = Your security camera footage (evidence for compliance)
Logs = Your system health monitor (debugging and operations)

Audit events (evidence)

Use audit events when you need:

Compliance evidence - Prove what happened for auditors
Incident response - Investigate security incidents
Forensics - Reconstruct past decisions

Audit events capture:

Decision outcome (allow/deny/redact)
Reason codes (why the decision was made)
Correlation IDs (link related events)
Policy identifiers (which policy applied)
Redaction indicators (what was redacted)

Logs (operations)

Use logs when you need:

Debugging - Figure out why something isn’t working
Monitoring - Track system health and performance
Alerting - Get notified of issues

Logs capture:

Component lifecycle events
Performance metrics
Error conditions
Integration status

Do not treat logs as compliance evidence. Use audit events for compliance.

Default logging posture

TealTiger logging is secure by default: ✅ Structured - Key/value pairs, not unstructured text
✅ Redaction-safe - Sensitive data excluded by default
✅ Correlation-ready - Includes trace IDs for distributed tracing
❌ No prompts - User prompts excluded by default
❌ No responses - Model outputs excluded by default
❌ No secrets - API keys and tokens never logged

What logs include

Safe operational data:

{
  "timestamp": "2026-02-23T07:01:23.456Z",
  "level": "INFO",
  "component": "TealEngine",
  "version": "1.1.0",
  "correlation": {
    "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
    "span_id": "00f067aa0ba902b7"
  },
  "decision": {
    "action": "allow",
    "reason_code_family": "POLICY.ALLOWED"
  },
  "timing": {
    "evaluation_ms": 12,
    "total_ms": 45
  },
  "error_category": null
}

What logs exclude

Sensitive data that could leak: ❌ Raw user prompts
❌ Model completions
❌ API keys or tokens
❌ PII (names, emails, phone numbers)
❌ Tool payload values
❌ Full error stack traces with user data

If you need to log additional fields for debugging, apply redaction first and keep them out of production.

Log levels

TealTiger uses standard severity levels:

Level	When to use	Example
INFO	Normal operations	”Policy evaluated successfully”
WARN	Suspicious but not blocking	”Budget at 85% in MONITOR mode”
ERROR	Failures that need attention	”Policy evaluation failed”
DEBUG	Detailed troubleshooting	”Loaded 5 policies from config”

Examples

// INFO - Normal decision
{
  "level": "INFO",
  "message": "Policy decision: ALLOW",
  "decision": "allow",
  "policy_id": "pol_cost_001"
}

// WARN - Policy violation in MONITOR mode
{
  "level": "WARN",
  "message": "Policy violation detected (MONITOR mode)",
  "decision": "allow",
  "reason_code": "COST.BUDGET.EXCEEDED",
  "mode": "MONITOR"
}

// ERROR - Evaluation failure
{
  "level": "ERROR",
  "message": "Policy evaluation failed",
  "error_category": "SCHEMA_VALIDATION_ERROR",
  "policy_id": "pol_security_002"
}

Configuring log output

Console logging (default)

import { TealEngine } from 'tealtiger';

const engine = new TealEngine({
  policies: { /* ... */ },
  logging: {
    level: 'INFO',
    destination: 'console'
  }
});

File logging

const engine = new TealEngine({
  policies: { /* ... */ },
  logging: {
    level: 'INFO',
    destination: 'file',
    file: {
      path: './logs/tealtiger.log',
      rotation: 'daily',
      maxSize: '100MB'
    }
  }
});

Custom logger

const engine = new TealEngine({
  policies: { /* ... */ },
  logging: {
    level: 'INFO',
    destination: 'custom',
    custom: {
      log: (entry) => {
        // Send to your logging service
        myLogger.info(entry);
      }
    }
  }
});

Exporting to observability platforms

OpenTelemetry

import { TealEngine } from 'tealtiger';
import { trace } from '@opentelemetry/api';

const engine = new TealEngine({
  policies: { /* ... */ },
  telemetry: {
    opentelemetry: {
      enabled: true,
      tracer: trace.getTracer('tealtiger')
    }
  }
});

Datadog

const engine = new TealEngine({
  policies: { /* ... */ },
  logging: {
    destination: 'custom',
    custom: {
      log: (entry) => {
        // Send to Datadog
        datadogLogger.log(entry);
      }
    }
  }
});

Best practices

Use INFO in production - Avoid DEBUG unless troubleshooting
Monitor WARN logs - They indicate potential issues
Alert on ERROR logs - Set up alerts for failures
Correlate with traces - Use trace_id to link logs and audit events
Separate logs and audit - Send to different destinations
Rotate log files - Prevent disk space issues
Redact before logging - If you add custom fields, redact first

Audit Event Schema

Complete audit event structure

Cost Metadata

Track AI spending

Audit and Redaction

Security-by-default approach

OpenTelemetry Integration

Export to observability platforms

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Logs vs Audit Events

Audit events (evidence)

Logs (operations)

Default logging posture

What logs include

What logs exclude

Log levels

Examples

Configuring log output

Console logging (default)

File logging

Custom logger

Exporting to observability platforms

OpenTelemetry

Datadog

Best practices

Audit Event Schema

Cost Metadata

Audit and Redaction

OpenTelemetry Integration

​Logs vs Audit Events

​Audit events (evidence)

​Logs (operations)

​Default logging posture

​What logs include

​What logs exclude

​Log levels

​Examples

​Configuring log output

​Console logging (default)

​File logging

​Custom logger

​Exporting to observability platforms

​OpenTelemetry

​Datadog

​Best practices

​Related reading

Audit Event Schema

Cost Metadata

Audit and Redaction

OpenTelemetry Integration

Logs vs Audit Events

Audit events (evidence)

Logs (operations)

Default logging posture

What logs include

What logs exclude

Log levels

Examples

Configuring log output

Console logging (default)

File logging

Custom logger

Exporting to observability platforms

OpenTelemetry

Datadog

Best practices

Related reading