mod.rs

Overview

This file serves as a central module aggregating several submodules related to node operation, tracing, metrics, and key handling functionalities. It provides initialization and shutdown utilities for tracing and metrics collection, implements tracing spans for block flow events, manages shutdown signaling for graceful termination, and offers utility functions such as temporary file path generation and file hashing.

Modules

• account_boc_loader: Handles loading of account BOC (Bag of Cells) data.

• bp_resolver: Contains logic for resolving block producers.

• key_handling: Manages cryptographic keys and related operations.

• metrics: Implements metrics collection and reporting.

Constants and Static Variables

• TIMING_TARGET: &str: A static string constant used as a timing target identifier in tracing or metrics.

• SHUTDOWN_FINALIZATION_FLAG: OnceLock<bool>: Flag indicating if shutdown finalization has started.

• FINALIZATION_LOOPS_COUNTER: AtomicU32: Counter tracking the number of ongoing finalization loops during shutdown.

• SHUTDOWN_FLAG: OnceLock<bool>: Flag indicating if the shutdown process has fully completed.

Functions

verbose_filter() -> EnvFilter

Constructs a verbose logging filter for tracing_subscriber based on whether the feature flag "tvm_tracing" is enabled. It sets detailed trace-level logging for several components such as gossip, HTTP server, block manager, node, executor, network, TVM, builder, and others.

Returns:
An EnvFilter configured with component-specific log levels.

init_tracing() -> (Option<Metrics>, WorkerGuard)

Initializes the tracing and metrics systems with configuration derived from environment variables:

• Sets up tracing filters, selecting verbose output if the NODE_VERBOSE environment variable is set.

• Configures an OpenTelemetry (OTEL) tracer if an OTLP traces endpoint is specified via OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT.

• Installs tracing layers including a compact formatter and optionally an OTEL telemetry layer.

• Initializes metrics collection if an OTLP metrics endpoint is found, setting the global meter provider.

• Returns an optional Metrics instance and a WorkerGuard to keep the tracing appender alive.

Usage Example:

let (metrics_opt, guard) = init_tracing();
// Use metrics_opt for metrics recording if present
// Keep 'guard' alive for the lifetime of tracing

Returns:

• Option<Metrics>: Metrics collector if metrics endpoint is configured.

• WorkerGuard: Guard object to manage the lifetime of non-blocking tracing writer.

shutdown_tracing(tracing_guard: WorkerGuard)

Shuts down the tracing system gracefully.

• Calls OpenTelemetry's tracer provider shutdown.

• Drops the tracing worker guard to close the non-blocking writer.

Parameters:

• tracing_guard: The guard returned by init_tracing to be dropped.

init_tracer(endpoint: String) -> opentelemetry_sdk::trace::Tracer

Creates an OTLP tracer connected to the specified endpoint.

• Sets the resource attribute "service.name" to "acki-nacki-node".

• Builds an OTLP gRPC exporter using tonic.

• Constructs a batch exporter tracer provider with Tokio runtime.

• Registers the tracer provider as global.

• Returns a tracer named "node".

Parameters:

• endpoint: OTLP endpoint URL as a string.

Returns:
An OTLP Tracer instance for trace span creation.

init_noop_tracer() -> NoopTracer

Sets and returns a no-operation tracer provider and tracer, used when no telemetry exporter is configured.

Returns:
A NoopTracer instance.

block_flow_trace<const N: usize>(name: impl AsRef<str>, block_id: &BlockIdentifier, node_id: &NodeIdentifier, fields: [(&str, &str); N])

Creates and immediately ends a tracing span for a block flow event with the given name and associated metadata.

• Generates a trace ID based on the block identifier.

• Attaches node identifier and additional key-value fields as span attributes.

• Span name is prefixed with "block flow: " plus the provided name.

Parameters:

• name: Name of the block flow stage or event.

• block_id: Identifier of the block relevant to the trace.

• node_id: Identifier of the node emitting the trace.

• fields: Array of key-value pairs describing extra attributes.

Example Usage:

block_flow_trace(
    "processing",
    &block_id,
    &node_id,
    [("status", "started"), ("priority", "high")]
);

block_flow_trace_with_time<const N: usize>(time: Option<std::time::SystemTime>, name: impl AsRef<str>, block_id: &BlockIdentifier, node_id: &NodeIdentifier, fields: [(&str, &str); N])

Same as block_flow_trace but allows specifying an explicit start time for the span.

Parameters:

• time: Optional start time of the span.

• Other parameters are identical to block_flow_trace.

get_temp_file_path(parent_path: &Path) -> PathBuf

Generates a unique temporary file path within the specified directory.

• Repeatedly generates a random filename with .tmp extension until it finds one that does not exist.

• Returns the full path to this temporary file.

Parameters:

• parent_path: Directory path where the temp file should reside.

Returns:
A PathBuf representing the unique temporary file path.

start_shutdown()

Initiates the shutdown procedure for the application.

• Sets the SHUTDOWN_FINALIZATION_FLAG to true.

• Waits in a loop until the FINALIZATION_LOOPS_COUNTER reaches zero, indicating no ongoing finalization tasks.

• Sets the SHUTDOWN_FLAG to true to signal completion of shutdown preparations.

This function ensures that all finalization loops complete before marking the shutdown as fully active.

calc_file_hash<P: AsRef<Path>>(path: P) -> anyhow::Result<String>

Computes the SHA-256 hash of the contents of a file.

• Reads the entire file into memory.

• Updates a SHA-256 hasher with the file bytes.

• Returns the hex-encoded hash string.

Parameters:

• path: Path to the file to hash.

Returns:

• Ok(String): Hexadecimal representation of the file's SHA-256 hash.

• Err: If file reading or hashing fails.

Example Usage:

let hash = calc_file_hash("path/to/file.txt")?;
println!("File hash: {}", hash);

Implementation Details

• Uses the tracing and tracing_subscriber crates for structured logging and telemetry.

• Employs OpenTelemetry SDK for distributed tracing and metrics, supporting OTLP exporters.

• Shutdown coordination uses atomic flags and counters to synchronize finalization across threads.

• Temporary file generation is collision-safe by looping until a non-existent filename is found.

• Block flow tracing leverages block identifiers to generate deterministic trace IDs for correlation.

• All tracing spans are built with attributes that include node and block metadata for rich observability.

Interaction with Other System Components

• Interfaces with telemetry utilities (telemetry_utils) to determine OTLP metrics endpoints and initialize meter providers.

• References types from other crates/modules such as NodeIdentifier, BlockIdentifier, and cryptographic hashing (Sha256).

• Provides tracing and metrics initialization for the entire node runtime, impacting modules like gossip, HTTP server, block management, and executor.

• Shutdown flags and counters are used globally to coordinate graceful termination across multiple components.

Mermaid Diagram

flowchart TD
A[init_tracing] -->|returns| B[Metrics?, WorkerGuard]
A --> C[Setup tracing filters]
A --> D[Configure OTLP tracer if endpoint]
D --> E[init_tracer]
A --> F[Init metrics if endpoint]
G[shutdown_tracing] -->|uses| B
G --> H[Shutdown tracer provider]
G --> I[Drop WorkerGuard]
J[block_flow_trace] --> K[Create SpanBuilder]
J --> L[Set trace_id from BlockIdentifier]
J --> M["Set attributes (node, fields)"]
J --> N[Build and end span]
O[start_shutdown] --> P[Set SHUTDOWN_FINALIZATION_FLAG]
O --> Q[Wait for FINALIZATION_LOOPS_COUNTER == 0]
O --> R[Set SHUTDOWN_FLAG]
S[get_temp_file_path] --> T[Generate random tmp filename]
T --> U[Check if file exists]
U -->|exists| T
U -->|not exists| V[Return tmp file path]
W[calc_file_hash] --> X[Read file bytes]
X --> Y[Update Sha256 hasher]
Y --> Z[Return hex-encoded digest]