Logging

Logging & Tracing Conventions

Golem's service code uses the tracing crate for structured logging. Some existing code still uses the log facade; do not copy that pattern into new service logging unless the API being integrated specifically requires log records. Follow these conventions when adding or modifying tracing statements.

Core Rule: Structured Attributes Over Format Interpolation

Always pass dynamic values as structured key-value attributes. Keep the format string static (no {variable} interpolation).

✅ Good — structured attributes

debug!(
    shard_ids_current = shard_assignment.shard_ids.iter().join(", "),
    shard_ids_to_assign = shard_ids.iter().join(", "),
    "ShardService.assign_shards"
);

tracing::warn!(
    plugin = %grant_id,
    error = %err,
    "Locality recovery: failed to check locality"
);

error!(
    agent_id = owned_agent_id.to_string(),
    promise_id = promise_id.to_string(),
    error = %e,
    "Failed to complete promise"
);

info!(
    agent_id = owned_agent_id.to_string(),
    "Deleting cached status of fully archived worker"
);

❌ Bad — dynamic values in format string

tracing::error!("Failed to resolve target for plugin {grant_id}: {err}");

tracing::error!("Failed to send oplog entries to plugin {grant_id}: {err}");

debug!("Not enough memory to allocate {mem32} (available: {}), trying to free some up",
    self.worker_memory.available_permits());

debug!("Updating cached worker status for {owned_agent_id} to {status_value:?}");

Corrected versions

tracing::error!(
    plugin = %grant_id,
    error = %err,
    "Failed to resolve target for plugin"
);

tracing::error!(
    plugin = %grant_id,
    error = %err,
    "Failed to send oplog entries to plugin"
);

debug!(
    requested = mem32,
    available = self.worker_memory.available_permits(),
    "Not enough memory to allocate, trying to free some up"
);

debug!(
    agent_id = %owned_agent_id,
    status = ?status_value,
    "Updating cached worker status"
);

Attribute Formatting

Use tracing's field syntax for values:

Prefer % over .to_string() when Display is implemented.

Message String

• The message (last argument) should be a static string that describes what is happening.
• Use short, descriptive messages — typically "ServiceName.method_name" or a brief human-readable description.
• Record error causes as structured fields such as error = %error; do not interpolate them into the message.

Log Levels

Import Style

• Prefer importing the macros directly: use tracing::debug; (or use tracing::{debug, info, warn, error};)
• The fully-qualified tracing::warn!(...) form is also acceptable, especially when only one or two calls exist in a file.
• Prefer tracing over log for new service code. Use log only at an integration boundary that specifically consumes or emits log records.

Canonical Example

From golem-worker-executor/src/services/shard.rs:

debug!(
    shard_ids_current = shard_assignment.shard_ids.iter().join(", "),
    shard_ids_to_assign = shard_ids.iter().join(", "),
    "ShardService.assign_shards"
);

This demonstrates: structured attributes with descriptive keys, a static message identifying the operation, and no dynamic interpolation in the format string.