Introduce trace-dispatcher-api and restructure the package split#16
Draft
jutaro wants to merge 5 commits into
Draft
Introduce trace-dispatcher-api and restructure the package split#16jutaro wants to merge 5 commits into
jutaro wants to merge 5 commits into
Conversation
The trace-dispatcher-api / trace-dispatcher split was too coarse: output types (FormattedMessage, TraceObject, PreFormatted), the forwarder connection type (HowToConnect/Host/Port), and several utility/domain modules lived in the API package despite having no business being there — they pulled in bytestring, async, cborg-json, and time as transitive API dependencies. Moved to trace-dispatcher: FormattedMessage, TraceObject, PreFormatted → Cardano.Logging.Formatter HowToConnect, Host, Port → Cardano.Logging.Tracer.Forward Cardano.Logging.Utils, Types.NodeInfo, Types.NodeStartupInfo, Types.TraceMessage trace-dispatcher-api now exposes exactly two modules (Cardano.Logging.Types, Cardano.Logging.Trace) covering the Trace newtype, the LogFormatting/MetaTrace typeclasses, core combinators, and the TraceControl dependency chain. Removed four no-longer-needed build-depends (async, bytestring, cborg-json, time). New Cardano.Logging.API is added as the single-import front door for the package, re-exporting both modules with a module haddock that explains the two-tier role and guides users toward Cardano.Logging (from trace-dispatcher) when they need the full backend stack. Cardano.Logging (the trace-dispatcher mega-module) gains a three-step usage haddock and no longer re-exports FrequencyLimiter or TraceDispatcherMessage, which are internal implementation details.
jutaro
force-pushed
the
jutaro/trace-dispatcher-api
branch
from
e5fd150 to
a4d50d8
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Extracts a new thin package trace-dispatcher-api from trace-dispatcher, then refines its internal structure so each module has a single, well-named responsibility.
Motivation
Previously all tracing types and combinators lived inside trace-dispatcher. Any package that only needed to instrument its own code — define LogFormatting/MetaTrace instances and call traceWith — was forced to depend on the full backend stack (EKG, Prometheus, CBOR forwarding, async, YAML config parser, …). The split makes the stable API surface available as a lightweight dependency.
Changes
New package: trace-dispatcher-api
Contains only what a package needs to define trace types and emit messages:
Cardano.Logging.Types — the Trace carrier, TraceControl GADT, LogFormatting/MetaTrace typeclasses, and the full TraceConfig/BackendConfig dependency chain (required because TraceControl embeds it in-band).
Cardano.Logging.Trace — filtering and per-message annotation combinators (filterTraceBySeverity, setSeverity, withPrivacy, withNames, …).
Cardano.Logging.API — a single-import front door re-exporting both modules, with a module haddock that explains when to use this package versus trace-dispatcher.
Build-depends for trace-dispatcher-api is kept deliberately small: no async, bytestring, cborg-json, time, or YAML.
trace-dispatcher-api split into 7 focused modules
The two original large files (Types.hs at 568 lines, Trace.hs at 389 lines) were further divided along natural seams:
Module Contents
Cardano.Logging.Types.Annotations SeverityS/F, Privacy, DetailLevel, Metric, Namespace, LoggingContext
Cardano.Logging.Types.Config BackendConfig, TraceConfig, ForwarderAddr/Mode, Verbosity, PrometheusSimpleRun
Cardano.Logging.Types.Doc ConfigReflection, DocCollector, LogDoc
Cardano.Logging.Types (hub) Trace, TraceControl, LogFormatting, MetaTrace, Folding + re-exports
Cardano.Logging.Trace.Combinators traceWith, contramapM, foldTraceM, routingTrace, contramap'
Cardano.Logging.Trace (hub) filter*, set/with severity/privacy/detail/names + re-export Combinators
Cardano.Logging.API front-door re-export of Types + Trace
The dependency graph is a strict DAG with no cycles: Annotations → Config → Doc → Types → Combinators → Trace → API.
trace-dispatcher tightened
FormattedMessage/TraceObject/PreFormatted moved from the API into Cardano.Logging.Formatter.
HowToConnect/Host/Port moved into Cardano.Logging.Tracer.Forward.
Utils, Types.NodeInfo, Types.NodeStartupInfo, Types.TraceMessage moved from the API into trace-dispatcher.
Cardano.Logging (the mega-module) gains a three-step usage haddock and no longer re-exports FrequencyLimiter or TraceDispatcherMessage as public API.
Compatibility
All changes are additive from the perspective of existing consumers of trace-dispatcher: import Cardano.Logging continues to export the same surface. The new sub-modules are opt-in additional import targets.