Logging

Asynchronous event logging for compliance and observability.

Overview

SekuireLogger provides:

• Batched logging - Events are buffered and sent in batches
• Fire-and-forget - Non-blocking, won't slow down your agent
• Compliance events - Track tool usage, policy checks, model calls
• Health heartbeats - Automatic liveness reporting

┌─────────────┐     Buffer      ┌─────────────┐     Batch      ┌─────────────┐
│   Agent     │ ──────────────▶ │   Logger    │ ─────────────▶ │  Sekuire    │
│             │    log_event()  │   (50 max)  │   POST /logs   │    API      │
│  Tool call  │                 │             │                │             │
│  LLM call   │                 │  flush()    │                │  Dashboard  │
└─────────────┘                 └─────────────┘                └─────────────┘

---

Event Types

Type	Description	Example
tool_execution	Tool was invoked	Calculator, HTTP request
model_call	LLM API call	GPT-4, Claude
policy_violation	Action blocked by policy	Denied network access
policy_check	Policy was evaluated	Checked tool whitelist
network_access	External network call	API request
file_access	File system operation	Read/write file
health	Agent health status	Heartbeat

---

Severity Levels

Level	Use Case
debug	Detailed debugging information
info	Normal operations
warn	Potential issues
error	Failures and errors

---

Usage

Python

from sekuire_sdk.logger import SekuireLogger, LoggerConfig, EventType, Severity

# Create logger config
config = LoggerConfig(
    sekuire_id="7f8a9b3c2d1e...",
    api_base_url="https://api.sekuire.ai",
    api_key="your-api-key",
    workspace_id="ws_abc123",
    environment="production",
    batch_size=50,        # Flush after 50 events
    flush_interval=10.0,  # Or every 10 seconds
)

# Create logger
logger = SekuireLogger(config)

# Start background tasks (flush loop, heartbeat)
await logger.start_background_tasks()

# Log events (non-blocking)
logger.log_event(
    event_type=EventType.TOOL_EXECUTION,
    severity=Severity.INFO,
    event_data={
        "tool_name": "calculator",
        "input": {"expression": "2 + 2"},
        "output": "4",
        "duration_ms": 5,
    }
)

logger.log_event(
    event_type=EventType.MODEL_CALL,
    severity=Severity.INFO,
    event_data={
        "provider": "openai",
        "model": "gpt-4",
        "prompt_tokens": 150,
        "completion_tokens": 50,
        "latency_ms": 1200,
    }
)

# Log policy violations
logger.log_event(
    event_type=EventType.POLICY_VIOLATION,
    severity=Severity.WARN,
    event_data={
        "action": "network:request",
        "resource": "https://blocked-site.com",
        "policy": "network_whitelist",
        "reason": "Domain not in whitelist",
    }
)

# Graceful shutdown (flushes remaining events)
await logger.shutdown()

TypeScript

import { SekuireLogger } from '@sekuire/sdk';

// Create logger
const logger = new SekuireLogger({
  sekuireId: '7f8a9b3c2d1e...',
  apiBaseUrl: 'https://api.sekuire.ai',
  apiKey: 'your-api-key',
  workspaceId: 'ws_abc123',
  environment: 'production',
  batchSize: 50,
  flushInterval: 10000,
});

// Log events
logger.logEvent('tool_execution', 'info', {
  toolName: 'calculator',
  input: { expression: '2 + 2' },
  output: '4',
  durationMs: 5,
});

logger.logEvent('model_call', 'info', {
  provider: 'openai',
  model: 'gpt-4',
  promptTokens: 150,
  completionTokens: 50,
  latencyMs: 1200,
});

// Optional: flush pending events before exit
await logger.flush();

---

Configuration Options (Python LoggerConfig)

Option	Type	Default	Description
sekuire_id	string	Required	Agent's Sekuire ID
api_base_url	string	http://localhost:9300	API endpoint
api_key	string	None	API key for authentication
session_id	string	Auto-generated	Unique session identifier
workspace_id	string	None	Workspace ID
environment	string	development	Environment name
enabled	bool	true	Enable/disable logging
batch_size	int	50	Events per batch
flush_interval	float	10.0	Seconds between flushes

TypeScript note: The TypeScript logger uses camelCase config keys (apiBaseUrl, batchSize, flushInterval) and flushInterval is in milliseconds. The logger starts timers on construction, so there is no start()/shutdown() method.

---

Background Tasks

The logger runs two background tasks:

Flush Loop

Periodically sends buffered events to the API:

# Events are flushed every flush_interval seconds
# Or immediately when batch_size is reached

Heartbeat Loop

Sends health status every 30 seconds:

# Automatic health heartbeat
# Appears in dashboard as agent liveness

---

Manual Flush

Force an immediate flush:

# Flush all buffered events now
await logger.flush()

---

Status Check

Get logger status for debugging:

status = logger.get_status()
print(status)
# {
#   'enabled': True,
#   'buffered_events': 12,
#   'session_id': 'abc123...',
#   'environment': 'production',
#   'is_running': True
# }

---

Integration with Agent

The SDK automatically logs events when using the agent:

from sekuire_sdk import get_agent

# Agent automatically logs:
# - Tool executions
# - LLM calls
# - Policy checks
agent = await get_agent('assistant')

# This chat will generate log events
response = await agent.chat('Calculate 2 + 2')

---

Compliance Logging Best Practices

1. Always log policy violations - Required for compliance audits
2. Include context - Add relevant metadata to events
3. Use appropriate severity - ERROR for failures, WARN for violations
4. Don't log PII - Sanitize sensitive data before logging
5. Graceful shutdown - Always call shutdown() to flush remaining events

# Good: Sanitized data
logger.log_event(EventType.FILE_ACCESS, Severity.INFO, {
    "action": "read",
    "path": "/data/report.csv",
    "size_bytes": 1024,
    # Don't include file contents!
})

# Bad: Includes sensitive data
logger.log_event(EventType.FILE_ACCESS, Severity.INFO, {
    "action": "read",
    "path": "/data/report.csv",
    "contents": "... sensitive data ...",  # DON'T DO THIS
})

---

Viewing Logs

Logs appear in the Sekuire dashboard:

1. Go to Workspace > Agents
2. Select your agent
3. Click Logs tab

Filter by:

• Event type
• Severity
• Time range
• Session ID

Next Steps

• Telemetry - OpenTelemetry integration
• Policy Enforcement - Policy violation logging
• Beacon - Health heartbeats