Building Collectors

This guide provides considerations for designing, implementing and deploying Breeze Agent collectors.

Lifecycle

• Collectors run as part of the Breeze execution cycle.
• They must be:
  • Idempotent — running multiple times should not cause side effects.
  • Fast — aim for <10s per collector to keep total agent runtime low.
• On hard failure, exit with a non‑zero status so issues surface in logs.

Inputs and Outputs

• Inputs:
  • Local OS state (files, processes, services).
  • Application APIs (HTTP, database queries, etc.), where appropriate.
• Outputs:
  • Emit JSON or key=value facts in a format Breeze can parse.
  • Write to STDOUT or a designated output file location that the agent reads.

Performance and Reliability

• Avoid heavy operations (for example, full database dumps or expensive API calls) during each run.
• Cache expensive data on disk when possible and refresh it less frequently.
• Log concise error messages so troubleshooting is straightforward, but avoid logging sensitive data.

Packaging and Deployment

• Keep collectors small and self‑contained so they can be:
  • Distributed with Breeze via plugins, or
  • Deployed via your existing configuration/automation tooling.
• Version your collectors and document:
  • The facts they emit.
  • Any dependencies or environment variables they rely on.

Examples

Below are collector ideas to inspire your own extensions.

• Disk usage exporter
  • Inspect mounted filesystems and emit facts such as:
    • fs.<mount>.used_percent
    • fs.<mount>.free_gb
• HTTP health probe
  • Call an application health endpoint and emit:
    • app.status (ok/ degraded/ down)
    • app.latency_ms
• Certificate expiry checker
  • Parse TLS certificate metadata and emit:
    • cert.<name>.days_to_expiry
• Queue depth monitor
  • Query a message queue or job system and emit:
    • queue.<name>.depth
    • queue.<name>.oldest_age_sec

Use these patterns together with Custom Metrics & Facts to decide how to name and group your custom facts.