Overview#

ProcessEventSource is a component in the procmond module that implements the EventSource trait for the collector-core framework. It is responsible for collecting process information from the system and streaming it as events to the collector runtime. This component wraps the existing process collection logic (formerly handled by ProcessMessageHandler and IPC servers) and integrates it directly into the unified event source model of collector-core, eliminating the need for separate IPC communication for process data in procmond procmond/src/event_source.rs.

Architecture#

Role within collector-core#

ProcessEventSource acts as a bridge between the process enumeration logic and the collector-core event streaming system. It implements the EventSource trait, providing methods for capability negotiation, event streaming, health checks, and lifecycle management. When registered with a Collector, it periodically enumerates system processes, converts them into ProcessEvent objects, and sends them as CollectionEvents through an asynchronous channel. The collector runtime manages event batching, backpressure, telemetry, and IPC, providing a unified interface for all event sources collector-core/src/collector.rs.

Configuration and Management#

Configuration Parameters#

Process collection is configured via the ProcessSourceConfig struct, which includes:

• collection_interval (Duration): Interval between process collection cycles. Default is 30 seconds.
• collect_enhanced_metadata (bool): Whether to collect enhanced metadata (e.g., CPU/memory usage, start time). Default is true.
• max_processes_per_cycle (usize): Maximum number of processes to collect per cycle. 0 means unlimited. Default is 0.
• compute_executable_hashes (bool): Whether to compute executable hashes. Default is false. When enabled, a shared MultiAlgorithmHasher must be injected via with_hasher() to activate hash computation.

Example:

use procmond::event_source::{ProcessEventSource, ProcessSourceConfig};
use daemoneye_lib::storage::DatabaseManager;
use daemoneye_lib::integrity::{HasherConfig, MultiAlgorithmHasher};
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::Mutex;

let db_manager = Arc::new(Mutex::new(DatabaseManager::new("/var/lib/daemoneye/processes.db")?));
let config = ProcessSourceConfig {
    collection_interval: Duration::from_secs(60),
    collect_enhanced_metadata: false,
    max_processes_per_cycle: 1000,
    compute_executable_hashes: true,
};

// Construct the shared hash engine when compute_executable_hashes is enabled
let hasher = Arc::new(MultiAlgorithmHasher::new(HasherConfig::default())?);
let source = ProcessEventSource::with_config(db_manager, config)
    .with_hasher(Some(hasher));

procmond/src/event_source.rs

CLI Options#

When running procmond, process collection parameters can be set via CLI options:

• --interval <seconds>: Sets the collection interval (default: 30, min: 5, max: 3600).
• --max_processes <number>: Sets the maximum number of processes to collect per cycle (default: 0, unlimited).
• --enhanced_metadata: Enables enhanced metadata collection.
• --compute_hashes: Enables executable hashing.

Example CLI usage:

procmond --interval 60 --max_processes 500 --enhanced_metadata --compute_hashes

These options are parsed and mapped to the ProcessSourceConfig struct during initialization procmond/src/main.rs.

Lifecycle and Event Streaming#

ProcessEventSource is registered with the Collector and started as part of the collector runtime. It runs a loop that collects processes at the configured interval, sending events via a channel, and listens for a shutdown signal to stop gracefully. The collector runtime handles event batching, IPC, telemetry, and health checks for all registered sources collector-core/src/collector.rs.

When a shared hash engine is attached via with_hasher(), the source runs a post-enumeration hash pass to populate executable_hash and hash_algorithm fields. The pass deduplicates by unique executable path, hashes in parallel (bounded concurrency via the engine's internal semaphore), and respects a request-scoped deadline to prevent stalls on slow storage. Hash failures are logged but non-fatal — events with missing hashes are delivered with executable_hash: None.

Migration from IPC Server Setups#

Previously, procmond used a dedicated IPC server and ProcessMessageHandler to communicate process data to other components via protobuf messages. With the introduction of ProcessEventSource and the collector-core framework, process collection is now integrated directly as an event source. This architectural change removes the need for a separate IPC server for process data, centralizes configuration and lifecycle management, and enables unified event streaming, capability negotiation, and telemetry across all sources procmond/src/event_source.rs procmond/src/lib.rs.

Example: Registering ProcessEventSource#

use procmond::event_source::{ProcessEventSource, ProcessSourceConfig};
use daemoneye_lib::storage::DatabaseManager;
use daemoneye_lib::integrity::{HasherConfig, MultiAlgorithmHasher};
use collector_core::{Collector, CollectorConfig};
use std::sync::Arc;
use std::time::Duration;
use tokio::sync::Mutex;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let db_manager = Arc::new(Mutex::new(DatabaseManager::new("/var/lib/daemoneye/processes.db")?));
    let process_config = ProcessSourceConfig {
        collection_interval: Duration::from_secs(30),
        collect_enhanced_metadata: true,
        max_processes_per_cycle: 0,
        compute_executable_hashes: true,
    };

    // Construct shared hash engine at composition root when hashing is enabled
    let hasher = Arc::new(MultiAlgorithmHasher::new(HasherConfig::default())?);
    let process_source = ProcessEventSource::with_config(db_manager, process_config)
        .with_hasher(Some(hasher));

    let collector_config = CollectorConfig::default().with_component_name("procmond".to_string());
    let mut collector = Collector::new(collector_config);
    collector.register(Box::new(process_source))?;
    collector.run().await?;
    Ok(())
}

procmond/src/main.rs

Summary Table: Key Parameters#

For further details, see the ProcessEventSource implementation and procmond CLI setup.