Tracing libraries

[fmaste]

Move Tracing Instances to Ouroboros-Network

Summary

This PR moves the LogFormatting and MetaTrace instances from the cardano-node executable (specifically src/Cardano/Node/Tracing/Tracers/**) to the ouroboros-network package.

Architectural Changes

To handle dependencies correctly and keep components reusable, two new sub-libraries have been created in ouroboros-network.cabal:

1. framework-tracing:

   • Contains instances related to lower-level components.
   • Depends only on the framework sub-library.
   • Note: Instances related to network-mux (from the network-mux package) are located here. This satisfies the requirement from network-mux maintainers to keep that package low-level and free of high-level tracing dependencies while providing the necessary instances for the framework.

2. tracing:

   • Contains instances related to higher-level components (e.g., PeerSelection).
   • Depends on the ouroboros-network library (which in turn uses framework).

Motivation

• Reuse: This move allows other projects based on the Ouroboros networking layer, such as dmq-node, to reuse these tracing instances without duplicating code. PR #32 is a work-in-progress updating dmq-node to depend on these new sub-libraries.
• Decoupling: This refactor is a key step in decoupling the core networking code from cardano-diffusion.

Hierarchy Note

Most tracing modules ended up under the Ouroboros.Network.Tracing.PeerSelection hierarchy. This is a side effect of the migration strategy where one module was created per data type, reflecting the structure of the data types being traced.

Modifications & Cut Dependencies

The instances were modified to compile within ouroboros-network, necessitating the removal of dependencies on cardano-diffusion and ouroboros-consensus.

Specific items requiring attention or review:

• Network.Mux.Tracing:
  • Removed references to ExnMempoolTimeout (from ouroboros-consensus) in impliesMempoolTimeoutHard. It now uses string matching (isPrefixOf) to identify these exceptions, avoiding a heavy dependency on the consensus layer.
  • New Implementation: Added explicit handling for constructors TraceNewMux and TraceStarting to ensure the instances are complete and compile against the current network-mux definitions.
• PeerSelection.Governor.DebugPeerSelection:
  • Removed imports from cardano-diffusion.
  • Changed the LogFormatting instance for DebugPeerSelection to use generic types (extraState, extraFlags, etc.) instead of specific Cardano.* types.
  • Commented out specific counters (e.g., counters field in forMachine) that relied on cardanoPeerSelectionStatetoCounters.
• PeerSelection.Governor.PeerSelectionCounters:
  • Generalized the LogFormatting instance to PeerSelectionCounters extraCounters.
  • Action Item: Commented out machine output fields for Bootstrap Peers (e.g., knownBootstrapPeers, activeBootstrapPeers) as they relied on Cardano.view* functions from cardano-diffusion.
• PeerSelection.Governor.TracePeerSelection:
  • Removed TraceLedgerStateJudgementChanged and TraceUseBootstrapPeersChanged as they were ExtraTrace types imported from cardano-diffusion.
  • TraceTargetsChanged: A field present in cardano-node master might be missing here (see TODO in source).
  • Added extraTrace to the TracePeerSelection instance head to support the generic type.
  • New Implementation: Added explicit handling for the ExtraTrace constructor in LogFormatting and MetaTrace instances (namespaceFor, severityFor, etc.) to resolve non-exhaustive pattern match errors. This mirrors how Mux.TraceNewMux and Mux.TraceStarting are handled, ensuring the code compiles while acknowledging that the specific trace types are now generic.

Origin

Instances extracted from cardano-node "master" (2026-02-11, 85869e9dd21d9dac7c4381418346e97259c3303b)

Checklist

Quality

• Commit sequence makes sense and have useful messages, see ref.
• New tests are added and existing tests are updated.
• Self-reviewed the PR.

Maintenance

• Linked an issue or added the PR to the current sprint of ouroboros-network project.
• Added labels.
• Updated changelog files.
• The documentation has been properly updated, see ref.

[crocodile-dentist]

See also my comments re network-mux in #5235 and whether to make it a separate library instead.