hs-opentelemetry-api 0.0.3.5 → 0.0.3.6

raw patch · 6 files changed

+77/−48 lines, 6 filesPVP: minor bump suggested

API additions: PVP suggests at least a minor version bump

API changes (from Hackage documentation)

Files

• ChangeLog.md +5/−0
• hs-opentelemetry-api.cabal +1/−1
• src/OpenTelemetry/Internal/Trace/Types.hs +48/−40
• src/OpenTelemetry/Trace/Id.hs +12/−1
• src/OpenTelemetry/Trace/Sampler.hs +1/−1
• src/OpenTelemetry/Util.hs +10/−5

@@ -1,5 +1,10 @@ # Changelog for hs-opentelemetry-api +## 0.0.3.6++- GHC 9.4 support+- Add Show instances to several api types+ ## 0.0.3.1  - `adjustContext` uses an empty context if one hasn't been created on the current thread yet instead of acting as a no-op.

@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack  name:           hs-opentelemetry-api-version:        0.0.3.5+version:        0.0.3.6 synopsis:       OpenTelemetry API for use by libraries for direct instrumentation or wrapper packages. description:    Please see the README on GitHub at <https://github.com/iand675/hs-opentelemetry/tree/main/api#readme> category:       OpenTelemetry, Telemetry, Monitoring, Observability, Metrics

@@ -34,10 +34,10 @@   = Success   | Failure (Maybe SomeException) --- | An identifier for the library that provides the instrumentation for a given Instrumented Library. +-- | An identifier for the library that provides the instrumentation for a given Instrumented Library. -- Instrumented Library and Instrumentation Library may be the same library if it has built-in OpenTelemetry instrumentation. ----- The inspiration of the OpenTelemetry project is to make every library and application observable out of the box by having them call OpenTelemetry API directly. +-- The inspiration of the OpenTelemetry project is to make every library and application observable out of the box by having them call OpenTelemetry API directly. -- However, many libraries will not have such integration, and as such there is a need for a separate library which would inject such calls, using mechanisms such as wrapping interfaces, -- subscribing to library-specific callbacks, or translating existing telemetry into the OpenTelemetry model. --@@ -87,11 +87,11 @@   -- ^ Called after a span is ended (i.e., the end timestamp is already set). This method is called synchronously within the 'OpenTelemetry.Trace.endSpan' API, therefore it should not block or throw an exception.   , processorShutdown :: IO (Async ShutdownResult)   -- ^ Shuts down the processor. Called when SDK is shut down. This is an opportunity for processor to do any cleanup required.-  -- +  --   -- Shutdown SHOULD be called only once for each SpanProcessor instance. After the call to Shutdown, subsequent calls to OnStart, OnEnd, or ForceFlush are not allowed. SDKs SHOULD ignore these calls gracefully, if possible.   --   -- Shutdown SHOULD let the caller know whether it succeeded, failed or timed out.-  -- +  --   -- Shutdown MUST include the effects of ForceFlush.   --   -- Shutdown SHOULD complete or abort within some timeout. Shutdown can be implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. OpenTelemetry client authors can decide if they want to make the shutdown timeout configurable.@@ -107,7 +107,7 @@   -- ForceFlush SHOULD complete or abort within some timeout. ForceFlush can be implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. OpenTelemetry client authors can decide if they want to make the flush timeout configurable.   } -{- | +{- | 'Tracer's can be created from a 'TracerProvider'. -} data TracerProvider = TracerProvider@@ -122,7 +122,7 @@   }  -- | The 'Tracer' is responsible for creating 'Span's.--- +-- -- Each 'Tracer' should be associated with the library or application that -- it instruments. data Tracer = Tracer@@ -136,25 +136,28 @@   -- @since 0.0.10   } +instance Show Tracer where+  show Tracer {tracerName = name} = "Tracer { tracerName = " <> show name <> "}"+ {- | This is a link that is being added to a span which is going to be created. -A @Span@ may be linked to zero or more other @Spans@ (defined by @SpanContext@) that are causally related. -@Link@s can point to Spans inside a single Trace or across different Traces. @Link@s can be used to represent -batched operations where a @Span@ was initiated by multiple initiating Spans, each representing a single incoming +A @Span@ may be linked to zero or more other @Spans@ (defined by @SpanContext@) that are causally related.+@Link@s can point to Spans inside a single Trace or across different Traces. @Link@s can be used to represent+batched operations where a @Span@ was initiated by multiple initiating Spans, each representing a single incoming item being processed in the batch. -Another example of using a Link is to declare the relationship between the originating and following trace. -This can be used when a Trace enters trusted boundaries of a service and service policy requires the generation -of a new Trace rather than trusting the incoming Trace context. The new linked Trace may also represent a long +Another example of using a Link is to declare the relationship between the originating and following trace.+This can be used when a Trace enters trusted boundaries of a service and service policy requires the generation+of a new Trace rather than trusting the incoming Trace context. The new linked Trace may also represent a long running asynchronous data processing operation that was initiated by one of many fast incoming requests. -When using the scatter/gather (also called fork/join) pattern, the root operation starts multiple downstream -processing operations and all of them are aggregated back in a single Span. -This last Span is linked to many operations it aggregates. -All of them are the Spans from the same Trace. And similar to the Parent field of a Span. -It is recommended, however, to not set parent of the Span in this scenario as semantically the parent field -represents a single parent scenario, in many cases the parent Span fully encloses the child Span. +When using the scatter/gather (also called fork/join) pattern, the root operation starts multiple downstream+processing operations and all of them are aggregated back in a single Span.+This last Span is linked to many operations it aggregates.+All of them are the Spans from the same Trace. And similar to the Parent field of a Span.+It is recommended, however, to not set parent of the Span in this scenario as semantically the parent field+represents a single parent scenario, in many cases the parent Span fully encloses the child Span. This is not the case in scatter/gather and batch scenarios. -} data NewLink = NewLink@@ -168,22 +171,22 @@ {- | This is an immutable link for an existing span. -A @Span@ may be linked to zero or more other @Spans@ (defined by @SpanContext@) that are causally related. -@Link@s can point to Spans inside a single Trace or across different Traces. @Link@s can be used to represent -batched operations where a @Span@ was initiated by multiple initiating Spans, each representing a single incoming +A @Span@ may be linked to zero or more other @Spans@ (defined by @SpanContext@) that are causally related.+@Link@s can point to Spans inside a single Trace or across different Traces. @Link@s can be used to represent+batched operations where a @Span@ was initiated by multiple initiating Spans, each representing a single incoming item being processed in the batch. -Another example of using a Link is to declare the relationship between the originating and following trace. -This can be used when a Trace enters trusted boundaries of a service and service policy requires the generation -of a new Trace rather than trusting the incoming Trace context. The new linked Trace may also represent a long +Another example of using a Link is to declare the relationship between the originating and following trace.+This can be used when a Trace enters trusted boundaries of a service and service policy requires the generation+of a new Trace rather than trusting the incoming Trace context. The new linked Trace may also represent a long running asynchronous data processing operation that was initiated by one of many fast incoming requests. -When using the scatter/gather (also called fork/join) pattern, the root operation starts multiple downstream -processing operations and all of them are aggregated back in a single Span. -This last Span is linked to many operations it aggregates. -All of them are the Spans from the same Trace. And similar to the Parent field of a Span. -It is recommended, however, to not set parent of the Span in this scenario as semantically the parent field -represents a single parent scenario, in many cases the parent Span fully encloses the child Span. +When using the scatter/gather (also called fork/join) pattern, the root operation starts multiple downstream+processing operations and all of them are aggregated back in a single Span.+This last Span is linked to many operations it aggregates.+All of them are the Spans from the same Trace. And similar to the Parent field of a Span.+It is recommended, however, to not set parent of the Span in this scenario as semantically the parent field+represents a single parent scenario, in many cases the parent Span fully encloses the child Span. This is not the case in scatter/gather and batch scenarios. -} data Link = Link@@ -217,7 +220,7 @@   | FlushSuccess   -- ^ Flushing spans to all associated exporters succeeded.   | FlushError-  -- ^ One or more exporters failed to successfully export one or more +  -- ^ One or more exporters failed to successfully export one or more   -- unexported spans.   deriving (Show) @@ -249,20 +252,20 @@ -} data SpanKind   = Server-  -- ^ Indicates that the span covers server-side handling of a synchronous RPC or other remote request. +  -- ^ Indicates that the span covers server-side handling of a synchronous RPC or other remote request.   -- This span is the child of a remote @Client@ span that was expected to wait for a response.   | Client-  -- ^ Indicates that the span describes a synchronous request to some remote service. +  -- ^ Indicates that the span describes a synchronous request to some remote service.   -- This span is the parent of a remote @Server@ span and waits for its response.   | Producer-  -- ^ Indicates that the span describes the parent of an asynchronous request. -  -- This parent span is expected to end before the corresponding child @Producer@ span, -  -- possibly even before the child span starts. In messaging scenarios with batching, +  -- ^ Indicates that the span describes the parent of an asynchronous request.+  -- This parent span is expected to end before the corresponding child @Producer@ span,+  -- possibly even before the child span starts. In messaging scenarios with batching,   -- tracing individual messages requires a new @Producer@ span per message to be created.   | Consumer-  -- ^ Indicates that the span describes the child of an asynchronous @Producer@ request. +  -- ^ Indicates that the span describes the child of an asynchronous @Producer@ request.   | Internal-  -- ^  Default value. Indicates that the span represents an internal operation within an application, +  -- ^  Default value. Indicates that the span represents an internal operation within an application,   -- as opposed to an operations with remote parents or children.   deriving (Show) @@ -316,7 +319,7 @@   , spanStatus :: SpanStatus   , spanTracer :: Tracer   -- ^ Creator of the span-  }+  } deriving (Show)  -- | A 'Span' is the fundamental type you'll work with to trace your systems. --@@ -339,6 +342,11 @@   | FrozenSpan SpanContext   | Dropped SpanContext +instance Show Span where+  show (Span _ioref) = "(mutable span)"+  show (FrozenSpan ctx) = show ctx+  show (Dropped ctx) = show ctx+ -- | TraceFlags with the @sampled@ flag not set. This means that it is up to the -- sampling configuration to decide whether or not to sample the trace. defaultTraceFlags :: TraceFlags@@ -455,7 +463,7 @@   -- ^ isRecording == true, AND Sampled flag MUST be set.   deriving (Show, Eq) --- | Interface that allows users to create custom samplers which will return a sampling SamplingResult based on information that +-- | Interface that allows users to create custom samplers which will return a sampling SamplingResult based on information that -- is typically available just before the Span was created. data Sampler = Sampler   { getDescription :: Text

@@ -1,3 +1,4 @@+{-# LANGUAGE CPP #-} {-# LANGUAGE BangPatterns #-} {-# LANGUAGE DerivingStrategies #-} {-# LANGUAGE GeneralizedNewtypeDeriving #-}@@ -19,7 +20,8 @@ -- transport-specific in format. Use newtypes for serialisation instead. -- ------------------------------------------------------------------------------module OpenTelemetry.Trace.Id ++module OpenTelemetry.Trace.Id   ( -- * Working with 'TraceId's     TraceId     -- ** Creating 'TraceId's@@ -113,8 +115,13 @@   isTrue#     (eqWord#       (or#+#if MIN_VERSION_base(4,17,0)+        (word64ToWord# (indexWord64Array# arr 0#))+        (word64ToWord# (indexWord64Array# arr 1#)))+#else         (indexWord64Array# arr 0#)         (indexWord64Array# arr 1#))+#endif       (int2Word# 0#))  -- | Access the byte-level representation of the provided 'TraceId'@@ -174,7 +181,11 @@ isEmptySpanId :: SpanId -> Bool isEmptySpanId (SpanId (SBS arr)) = isTrue#   (eqWord#+#if MIN_VERSION_base(4,17,0)+    (word64ToWord# (indexWord64Array# arr 0#))+#else     (indexWord64Array# arr 0#)+#endif     (int2Word# 0#))  -- | Access the byte-level representation of the provided 'SpanId'

@@ -55,7 +55,7 @@       pure (RecordAndSample, [], maybe TraceState.empty traceState mspanCtxt)   } --- | Returns @RecordAndSample@ always.+-- | Returns @Drop@ always. -- -- Description returns AlwaysOffSampler. --

@@ -78,14 +78,19 @@ getThreadId (ThreadId tid#) = fromIntegral (c_getThreadId tid#) {-# INLINE getThreadId #-} -data AppendOnlyBoundedCollection a = AppendOnlyBoundedCollection +data AppendOnlyBoundedCollection a = AppendOnlyBoundedCollection   { collection :: Builder a   , maxSize :: {-# UNPACK #-} !Int   , dropped :: {-# UNPACK #-} !Int   } +instance forall a. Show a => Show (AppendOnlyBoundedCollection a) where+  show AppendOnlyBoundedCollection {collection=c} =+    let vec = Builder.build c :: V.Vector a+        in show vec+ -- | Initialize a bounded collection that admits a maximum size-emptyAppendOnlyBoundedCollection :: +emptyAppendOnlyBoundedCollection ::      Int   -- ^ Maximum size   -> AppendOnlyBoundedCollection a@@ -95,10 +100,10 @@ appendOnlyBoundedCollectionValues (AppendOnlyBoundedCollection a _ _) = Builder.build a  appendOnlyBoundedCollectionSize :: AppendOnlyBoundedCollection a -> Int-appendOnlyBoundedCollectionSize (AppendOnlyBoundedCollection b _ _) = Builder.size b +appendOnlyBoundedCollectionSize (AppendOnlyBoundedCollection b _ _) = Builder.size b  appendOnlyBoundedCollectionDroppedElementCount :: AppendOnlyBoundedCollection a -> Int-appendOnlyBoundedCollectionDroppedElementCount (AppendOnlyBoundedCollection _ _ d) = d +appendOnlyBoundedCollectionDroppedElementCount (AppendOnlyBoundedCollection _ _ d) = d  appendToBoundedCollection :: AppendOnlyBoundedCollection a -> a -> AppendOnlyBoundedCollection a appendToBoundedCollection c@(AppendOnlyBoundedCollection b ms d) x = if appendOnlyBoundedCollectionSize c < ms@@ -108,7 +113,7 @@ data FrozenBoundedCollection a = FrozenBoundedCollection   { collection :: !(V.Vector a)   , dropped :: !Int-  }+  } deriving (Show)  frozenBoundedCollection :: Foldable f => Int -> f a -> FrozenBoundedCollection a frozenBoundedCollection maxSize_ coll = FrozenBoundedCollection (V.fromListN maxSize_ $ toList coll) (collLength - maxSize_)