Sensor Agent Details

Sensor Agent Details

Sensor Agents are responsible for collecting data from your systems. They can collect data from a variety of sources, including system metrics, application logs, and API endpoints.

Responsibilities

• Monitor defined sources (metrics, files, APIs, schedules, etc.) for trigger conditions.
• Report standardized trigger events to the orchestrator via Public API.
• Authenticate and communicate only via the Public API.
• Enforce tenant isolation and security boundaries.
• Support dynamic configuration and hot-reload of trigger definitions.

Interfaces

Outbound

Posts trigger_event messages to the orchestrator API.

{
  "event_type": "trigger_event",
  "agent_id": "string",
  "tenant_id": "string",
  "timestamp": "ISO8601",
  "trigger_type": "string",
  "payload": {}
}

Protocol: HTTPS REST API.
Registration: Registers with the Public API on startup.
Health Checks: Periodic status updates via API endpoint.
Configuration: Pulls trigger definitions and updates from orchestrator.

Example Event Flow

1. Sensor Agent detects a file change (via plugin).
2. Plugin emits a trigger_event with file metadata.
3. Event is posted to API endpoint POST /api/v1/triggers.
4. Orchestrator receives and processes the trigger event.

Extensibility

• Supports Python-based trigger plugins (SDK).
• Hot-reloadable plugin architecture.
• Pluggable monitoring and logging backends.

Sensor Plugin Architecture

Plugin Types

Sensor Plugins

Monitor systems and detect trigger conditions. Written in Python for ease of development and integration with monitoring tools.

Plugin Lifecycle

graph TD
    A[Plugin Registry] --> B[Download Plugin]
    B --> C[Validate Plugin]
    C --> D[Load Plugin]
    D --> E[Initialize Plugin]
    E --> F[Monitor & Detect]
    F --> G[Emit Trigger Events]
    G --> H[Continue Monitoring]

Plugin Security

All plugins execute within secure sandbox environments:

• Resource Limits: Memory and CPU usage strictly controlled
• Filesystem Access: Limited to allowed directories only
• Network Access: Restricted based on plugin requirements
• System Calls: Whitelist of allowed operations

Agent Configuration

Example Configuration

agent:
  type: sensor
  id: sensor-001
  orchestrator_url: https://agents.stavily.com
  auth_token: ${AGENT_TOKEN}
  heartbeat_interval: 30s
  plugin_check_interval: 300s

plugins:
  repositories:
    - name: prometheus-triggers
      url: https://github.com/stavily/prometheus-triggers
      version: v1.2.0
      auth_token: ${GITHUB_TOKEN}
    - name: file-watchers
      url: https://gitlab.com/stavily/file-watchers
      version: v2.1.0
      auth_token: ${GITLAB_TOKEN}

monitoring:
  prometheus_url: http://localhost:9090
  metrics_interval: 10s

security:
  plugin_sandbox: true
  resource_limits:
    memory: 256MB
    cpu: 0.5
    network: restricted

Monitoring and Observability

Metrics Collection

• Performance Metrics: Detection time, event frequency, success rates
• Health Metrics: Heartbeat status, plugin health, connectivity
• Security Metrics: Authentication attempts, sandbox violations
• Operational Metrics: Plugin downloads, configuration updates

Logging

Structured logging with configurable levels and outputs:

{
  "timestamp": "2025-01-15T10:30:00Z",
  "level": "INFO",
  "component": "sensor-agent",
  "agent_id": "sensor-001",
  "event": "trigger_detected",
  "workflow_id": "cpu-remediation-001",
  "plugin": "prometheus-trigger-v1.0.0",
  "metadata": {
    "metric": "cpu_usage_percent",
    "value": 95.2,
    "threshold": 90.0
  }
}