Expand description
guard-agent-rs: telemetry and monitoring agent for the Guard ecosystem.
This crate is the Rust counterpart of the Python guard-agent and
TypeScript guardagent telemetry agents. It ships security events,
metrics, and agent status to the Guard ingestion API
(POST /api/v1/events, /api/v1/metrics, /api/v1/status) with the same
reliability semantics:
- bounded per-kind buffers with
drop(evict oldest),block, andraiseoverflow policies; - flush triggers on buffer high watermark and on a fixed interval;
- at-least-once flush handshake: drain, send, confirm (delete persisted records) or requeue in original order;
- transport retries with exponential backoff, honoring
Retry-Afteron 429; - 413 split-or-drop with binary halving and a singleton drop threshold;
- permanent rejection (400, 404, 422) drops the batch without retrying;
- per-kind failure streaks with capped backoff and a computed degraded state;
- optional Redis persistence with TTL and startup reload.
Telemetry failures never propagate into the caller’s request path:
GuardAgent::send_event and GuardAgent::send_metric cannot fail,
and every error is observable through GuardAgent::get_stats, the
computed AgentStatus, logs, and the optional on_error hook.
§Usage
use guard_agent_rs::{AgentConfig, GuardAgent, SecurityEvent};
let mut config = AgentConfig::new("your-api-key-at-least-10-chars");
config.endpoint = "https://api.guard-core.com".to_owned();
config.install_id = Some("6f0a2880-1a2b-4c3d-9e4f-aabbccddeeff".to_owned());
let agent = GuardAgent::new(config).expect("valid configuration");
agent
.send_event(
SecurityEvent::new("rate_limited")
.with_ip_address("10.0.0.1")
.with_endpoint("/api/users")
.with_action_taken("blocked"),
)
.await;
let stats = agent.get_stats().await;
assert_eq!(stats.events_buffered, 1);See the repository README for the full reliability contract and the
persistence feature documentation for Redis-backed buffering.
Re-exports§
pub use agent::AgentStats;pub use agent::GuardAgent;pub use agent::LoopFailures;pub use bridge::GuardAgentTelemetry;guard-corepub use circuit_breaker::CircuitBreakerState;pub use config::AgentConfig;pub use config::BufferOverflowPolicy;pub use config::DEFAULT_BACKOFF_FACTOR;pub use config::DEFAULT_BUFFER_SIZE;pub use config::DEFAULT_COMPRESSION_THRESHOLD;pub use config::DEFAULT_DYNAMIC_RULE_INTERVAL_SECS;pub use config::DEFAULT_ENDPOINT;pub use config::DEFAULT_FLUSH_INTERVAL_SECS;pub use config::DEFAULT_HIGH_WATERMARK_RATIO;pub use config::DEFAULT_MAX_PAYLOAD_SIZE;pub use config::DEFAULT_RETRY_ATTEMPTS;pub use config::DEFAULT_SENSITIVE_HEADERS;pub use config::DEFAULT_STATUS_INTERVAL_SECS;pub use config::DEFAULT_TIMEOUT_SECS;pub use config::MIN_API_KEY_LEN;pub use config::MIN_DYNAMIC_RULE_INTERVAL_SECS;pub use config::MIN_STATUS_INTERVAL_SECS;pub use config::DEFAULT_REDIS_KEY_PREFIX;persistencepub use config::RedisConfig;persistencepub use encryption::PayloadEncryptor;pub use encryption::canonical_json;pub use encryption::urlsafe_base64_encode;pub use error::ConfigError;pub use error::ErrorStage;pub use error::GuardAgentError;pub use models::AgentHealth;pub use models::AgentStatus;pub use models::DynamicRules;pub use models::KNOWN_EVENT_TYPES;pub use models::MetricType;pub use models::SecurityEvent;pub use models::SecurityMetric;pub use persistence::RedisClientHandler;persistencepub use persistence::InMemoryRedisStore;pub use persistence::NAMESPACE_EVENTS;pub use persistence::NAMESPACE_METRICS;pub use persistence::PERSIST_TTL_SECONDS;pub use persistence::RedisHandler;pub use rate_limiter::RateLimiter;pub use utils::hash_ip;pub use utils::truncate_payload;
Modules§
- agent
- The
GuardAgent: buffered telemetry ingestion with at-least-once flush, per-kind failure backoff, degraded-state computation, and optional durable persistence. - bridge
guard-core - The guard-core-rs engine seam:
GuardAgentTelemetryimplements the facade’sTelemetryHandlersink trait. - circuit_
breaker - Client-side circuit breaker guarding the ingestion endpoint.
- config
- Agent configuration and validation.
- encryption
- AES-256-GCM payload encryption, mirroring
guard_agent/encryption.pybyte-for-byte on the wire. - error
- Typed errors for the guard-agent-rs telemetry agent.
- install_
id - Process-scoped install identifier resolution.
- logging_
utils - The agent’s log-record formatters, ported from the reference
logging_utils.py(JsonFormatter+ the text layout). - models
- Wire models mirroring the Python agent’s
SecurityEvent,SecurityMetric, andAgentStatuspayloads. - persistence
- Optional buffer persistence.
- rate_
limiter - Local client-side send rate limiter.
- signing
- HMAC-SHA256 request signing for the
X-Payload-Signatureheader. - transport
- HTTP transport: gzip compression, HMAC signing, retries with backoff,
429
Retry-Afterhandling, 413 split-or-drop, and permanent-rejection classification. - utils
- Shared helpers: backoff math,
Retry-Afterparsing, payload redaction, batch identifiers, and gzip compression.
Constants§
- AGENT_
VERSION - Version of this agent, reported in batch payloads and the User-Agent.