nri-prelude: thread an analytics callback through LogHandler

nri-env-parser/nri-env-parser.cabal

@@ -53,7 +53,7 @@ library
       base >=4.18 && <4.22
     , modern-uri >=0.3.1.0 && <0.4
     , network-uri >=2.6.2.0 && <2.8
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.1.0.0 && <0.8
     , text >=1.2.3.1 && <2.2
   default-language: Haskell2010
 
@@ -86,6 +86,6 @@ test-suite tests
       base >=4.18 && <4.22
     , modern-uri >=0.3.1.0 && <0.4
     , network-uri >=2.6.2.0 && <2.8
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.1.0.0 && <0.8
     , text >=1.2.3.1 && <2.2
   default-language: Haskell2010

nri-env-parser/package.yaml

@@ -16,7 +16,7 @@ extra-doc-files:
 library:
   dependencies: &dependencies
     - base >= 4.18 && < 4.22
-    - nri-prelude >= 0.1.0.0 && < 0.7
+    - nri-prelude >= 0.1.0.0 && < 0.8
     - modern-uri >= 0.3.1.0 && < 0.4
     - network-uri >= 2.6.2.0 && < 2.8
     - text >= 1.2.3.1 && < 2.2

nri-http/nri-http.cabal

@@ -65,7 +65,7 @@ library
     , mime-types >=0.1.0.0 && <0.2
     , network-uri >=2.6.0.0 && <2.8
     , nri-observability >=0.1.0.0 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , safe-exceptions >=0.1.7.0 && <1.3
     , text >=1.2.3.1 && <2.2
   default-language: Haskell2010
@@ -111,7 +111,7 @@ test-suite spec
     , mime-types >=0.1.0.0 && <0.2
     , network-uri >=2.6.0.0 && <2.8
     , nri-observability >=0.1.0.0 && <0.4
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , safe-exceptions >=0.1.7.0 && <1.3
     , text >=1.2.3.1 && <2.2
     , wai >=3.2.0 && <3.3

nri-http/package.yaml

@@ -17,7 +17,7 @@ library:
     - aeson >= 2.0 && < 2.3
     - base >= 4.18 && < 4.22
     - bytestring >= 0.10.8.2 && < 0.13
-    - nri-prelude >= 0.1.0.0 && < 0.7
+    - nri-prelude >= 0.7.0.0 && < 0.8
     - nri-observability >= 0.1.0.0 && < 0.5
     - conduit >= 1.3.0 && < 1.4
     - case-insensitive >= 1.1 && < 2.0
@@ -38,7 +38,7 @@ tests:
       - aeson >= 2.0 && < 2.3
       - base >= 4.18 && < 4.22
       - bytestring >= 0.10.8.2 && < 0.13
-      - nri-prelude >= 0.1.0.0 && < 0.7
+      - nri-prelude >= 0.7.0.0 && < 0.8
       - nri-observability >= 0.1.0.0 && < 0.4
       - conduit >= 1.3.0 && < 1.4
       - case-insensitive >= 1.1 && < 2.0

nri-http/test/Main.hs

@@ -233,6 +233,7 @@ spanForTask task = do
     Expect.fromIO <| do
       Platform.rootTracingSpanIO
         "test-request"
+        Platform.silentTrack
         (MVar.putMVar spanVar)
         "test-root"
         (\log -> Task.attempt log task)

nri-kafka/nri-kafka.cabal

@@ -80,7 +80,7 @@ library
     , hw-kafka-client >=4.0.3 && <5.0
     , nri-env-parser >=0.1.0.0 && <0.5
     , nri-observability >=0.1.1.1 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , safe-exceptions >=0.1.7.0 && <1.3
     , stm >=2.4 && <2.6
     , text >=1.2.3.1 && <2.2
@@ -125,7 +125,7 @@ executable pause-resume-bug-consumer
     , nri-env-parser >=0.1.0.0 && <0.5
     , nri-kafka
     , nri-observability >=0.1.1.1 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , safe-exceptions >=0.1.7.0 && <1.3
     , stm >=2.4 && <2.6
     , text >=1.2.3.1 && <2.2
@@ -174,7 +174,7 @@ executable pause-resume-bug-producer
     , nri-env-parser >=0.1.0.0 && <0.5
     , nri-kafka
     , nri-observability >=0.1.1.1 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , safe-exceptions >=0.1.7.0 && <1.3
     , stm >=2.4 && <2.6
     , text >=1.2.3.1 && <2.2
@@ -221,7 +221,7 @@ executable sync-write-benchmark
     , nri-env-parser >=0.1.0.0 && <0.5
     , nri-kafka
     , nri-observability >=0.1.1.1 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , safe-exceptions >=0.1.7.0 && <1.3
     , stm >=2.4 && <2.6
     , text >=1.2.3.1 && <2.2
@@ -284,7 +284,7 @@ test-suite tests
     , hw-kafka-client >=4.0.3 && <5.0
     , nri-env-parser >=0.1.0.0 && <0.5
     , nri-observability >=0.1.1.1 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , safe-exceptions >=0.1.7.0 && <1.3
     , stm >=2.4 && <2.6
     , text >=1.2.3.1 && <2.2

nri-kafka/package.yaml

@@ -23,7 +23,7 @@ dependencies:
   - hw-kafka-client >=4.0.3 && < 5.0
   - nri-env-parser >= 0.1.0.0 && < 0.5
   - nri-observability >= 0.1.1.1 && < 0.5
-  - nri-prelude >= 0.1.0.0 && < 0.7
+  - nri-prelude >= 0.7.0.0 && < 0.8
   - safe-exceptions >= 0.1.7.0 && < 1.3
   - stm >= 2.4 && < 2.6
   - text >= 1.2.3.1 && < 2.2

nri-kafka/src/Kafka/Worker/Internal.hs

@@ -456,6 +456,7 @@ cleanUp observabilityHandler rebalanceInfo stopping maybeException consumer = do
   -- at some point, k8s should report system crashes. In the mean time, we'll do it.
   Platform.rootTracingSpanIO
     requestId
+    Platform.silentTrack
     (Observability.report observabilityHandler requestId)
     "Kafka consumer shutting down"
     <| \log -> do

nri-kafka/src/Kafka/Worker/Partition.hs

@@ -248,6 +248,7 @@ processMsgLoop skipOrNot messageFormat commitOffsets observabilityHandler state
       (RequestId requestId, details) <- getTracingDetails (analytics state) processAttempts record
       Platform.rootTracingSpanIO
         requestId
+        Platform.silentTrack
         (Observability.report observabilityHandler requestId)
         "Assigned Kafka message"
         ( \log -> do

nri-log-explorer/nri-log-explorer.cabal

@@ -59,7 +59,7 @@ executable log-explorer
     , fuzzy >=0.1.0.0 && <0.2
     , io-streams >=1.5.0.0 && <1.6
     , microlens >=0.4.11.0 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.1.0.0 && <0.8
     , pcre-light >=0.4.1.0 && <0.4.2
     , process >=1.6.0.0 && <1.7
     , safe-exceptions >=0.1.7.0 && <1.3

nri-log-explorer/package.yaml

@@ -28,7 +28,7 @@ executables:
       - pcre-light >= 0.4.1.0 && < 0.4.2
       - unordered-containers >= 0.2.0.0 && < 0.3
       - microlens >= 0.4.11.0 && < 0.5
-      - nri-prelude >= 0.1.0.0 && < 0.7
+      - nri-prelude >= 0.1.0.0 && < 0.8
       - process >= 1.6.0.0 && < 1.7
       - safe-exceptions >= 0.1.7.0 && < 1.3
       - text >= 1.2.3.1 && < 2.2

nri-observability/nri-observability.cabal

@@ -77,7 +77,7 @@ library
     , http-client >=0.6.0 && <0.8
     , http-client-tls >=0.3.0 && <0.4
     , nri-env-parser >=0.1.0.0 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , random >=1.1 && <1.3
     , safe-exceptions >=0.1.7.0 && <1.3
     , stm >=2.4 && <2.6
@@ -123,7 +123,7 @@ executable memory-leak-test
     , http-client-tls >=0.3.0 && <0.4
     , nri-env-parser >=0.1.0.0 && <0.5
     , nri-observability
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , random >=1.1 && <1.3
     , safe-exceptions >=0.1.7.0 && <1.3
     , stm >=2.4 && <2.6
@@ -194,7 +194,7 @@ test-suite tests
     , http-client >=0.6.0 && <0.8
     , http-client-tls >=0.3.0 && <0.4
     , nri-env-parser >=0.1.0.0 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , random >=1.1 && <1.3
     , safe-exceptions >=0.1.7.0 && <1.3
     , stm >=2.4 && <2.6

nri-observability/package.yaml

@@ -26,7 +26,7 @@ dependencies:
   - http-client-tls >= 0.3.0 && < 0.4
   - hostname >= 1.0 && < 1.1
   - nri-env-parser >= 0.1.0.0 && < 0.5
-  - nri-prelude >= 0.1.0.0 && < 0.7
+  - nri-prelude >= 0.7.0.0 && < 0.8
   - random >= 1.1 && < 1.3
   - unordered-containers >= 0.2.0.0 && < 0.3
   - safe-exceptions >= 0.1.7.0 && < 1.3

nri-observability/scripts/memory-leak-test/Main.hs

@@ -35,6 +35,7 @@ runRequests handler =
     ( \requestId -> do
         Platform.rootTracingSpanIO
           requestId
+          Platform.silentTrack
           (handler.report requestId)
           ("Running task" ++ requestId)
           ( \log -> do

nri-postgresql/nri-postgresql.cabal

@@ -68,7 +68,7 @@ library
     , network >=3.1.0.0 && <3.3
     , nri-env-parser >=0.1.0.0 && <0.5
     , nri-observability >=0.1.0.0 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , postgresql-typed ==0.6.*
     , resource-pool >=0.2.0.0 && <0.5
     , resourcet >=1.2.0 && <1.4
@@ -126,7 +126,7 @@ test-suite tests
     , network >=3.1.0.0 && <3.3
     , nri-env-parser >=0.1.0.0 && <0.5
     , nri-observability >=0.1.0.0 && <0.5
-    , nri-prelude >=0.1.0.0 && <0.7
+    , nri-prelude >=0.7.0.0 && <0.8
     , postgresql-typed ==0.6.*
     , resource-pool >=0.2.0.0 && <0.5
     , resourcet >=1.2.0 && <1.4

nri-postgresql/package.yaml

@@ -23,7 +23,7 @@ dependencies:
   - network >= 3.1.0.0 && < 3.3
   - nri-env-parser >= 0.1.0.0 && < 0.5
   - nri-observability >= 0.1.0.0 && < 0.5
-  - nri-prelude >= 0.1.0.0 && < 0.7
+  - nri-prelude >= 0.7.0.0 && < 0.8
   - postgresql-typed >= 0.6 && < 0.7
   - resource-pool >= 0.2.0.0 && < 0.5
   - resourcet >= 1.2.0 && < 1.4

nri-postgresql/test/ObservabilitySpec.hs

@@ -53,6 +53,7 @@ spanForTask task =
     res <-
       Platform.rootTracingSpanIO
         "test-request"
+        Platform.silentTrack
         (MVar.putMVar spanVar)
         "test-root"
         (\log -> Task.attempt log task)

nri-prelude/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Unreleased
 
+# 0.7.0.0
+
+- **Breaking:** `Platform.rootTracingSpanIO` and the internal `mkHandler` now take an additional `Aeson.Value -> Task Never ()` callback for analytics event delivery. Existing callers should pass `Platform.silentTrack` to preserve previous behavior.
+- New: `Platform.Analytics.Internal.trackEvent`. The `.Internal` suffix is intentional — wrap it in your own typed `track` API. This module is NOT re-exported from `Platform`.
+- New: `Platform.silentTrack` (a no-op `Aeson.Value -> Task Never ()`). The `Task`-shaped callback gives wire-layer implementations access to the surrounding `LogHandler` for logging and tracing, so delivery errors flow through the normal observability pipeline.
+- New: `LogHandler.trackAnalyticsEvent` field. `nullHandler` defaults this to `silentTrack`.
 - Drop support for GHC 8.10.7, GHC 9.2.x, GHC 9.4.x, `aeson-1.x`
 - Support GHC 9.6.7, GHC 9.8.4, GHC 9.10.2, GHC 9.12.2, `bytestring-0.12.x.x`, `text-2.1.x`, `aeson-2.2.x.x`, `safe-coloured-text-0.3.x.x`, `safe-coloured-text-terminfo-0.3.x.x`, `lens-5.3.x`, `hedgehog-1.5.x`, `auto-update-0.2.x`, `containers-0.7.x`, `filepath-1.5.x`
 - Allow specifying where devlogs for log-explorer go through `NRI_DEV_LOG` environment variable.

nri-prelude/nri-prelude.cabal

@@ -5,7 +5,7 @@ cabal-version: 1.18
 -- see: https://github.com/sol/hpack
 
 name:           nri-prelude
-version:        0.6.1.2
+version:        0.7.0.0
 synopsis:       A Prelude inspired by the Elm programming language
 description:    Please see the README at <https://github.com/NoRedInk/haskell-libraries/tree/trunk/nri-prelude#readme>.
 category:       Web
@@ -45,6 +45,7 @@ library
       NriPrelude
       NriPrelude.Plugin
       Platform
+      Platform.Analytics.Internal
       Process
       Result
       Set
@@ -146,6 +147,7 @@ test-suite tests
       NriPrelude.Plugin
       NriPrelude.Plugin.GhcVersionDependent
       Platform
+      Platform.Analytics.Internal
       Platform.DevLog
       Platform.DoAnything
       Platform.Internal

nri-prelude/package.yaml

@@ -3,7 +3,7 @@ synopsis: A Prelude inspired by the Elm programming language
 description: Please see the README at <https://github.com/NoRedInk/haskell-libraries/tree/trunk/nri-prelude#readme>.
 homepage: https://github.com/NoRedInk/haskell-libraries/tree/trunk/nri-prelude#readme
 author: NoRedInk
-version: 0.6.1.2
+version: 0.7.0.0
 maintainer: haskell-open-source@noredink.com
 copyright: 2024 NoRedInk Corp.
 github: NoRedInk/haskell-libraries/nri-prelude
@@ -57,6 +57,7 @@ library:
     - NriPrelude
     - NriPrelude.Plugin
     - Platform
+    - Platform.Analytics.Internal
     - Process
     - Result
     - Set

nri-prelude/src/Platform.hs

@@ -13,6 +13,7 @@ module Platform
     logHandler,
     requestId,
     silentHandler,
+    Internal.silentTrack,
 
     -- * Creating custom tracingSpans in libraries
     Internal.tracingSpan,

nri-prelude/src/Platform/Analytics/Internal.hs

@@ -0,0 +1,46 @@
+{-# LANGUAGE FlexibleInstances #-}
+
+-- | Internal entry point for emitting analytics events from `Task` code.
+--
+-- This module is intentionally `.Internal`. It is NOT re-exported from
+-- the prelude's public `Platform` module. Higher layers (NoRedInk's
+-- `Analytics.track`) wrap this and own the user-facing API; downstream
+-- code that imports `Platform.Analytics.Internal` directly is bypassing
+-- the closed event dictionary and should be flagged in review.
+module Platform.Analytics.Internal
+  ( trackEvent,
+    AnalyticsEventDetails,
+  )
+where
+
+import qualified Data.Aeson as Aeson
+import NriPrelude
+import qualified Platform
+import qualified Platform.Internal as Internal
+import qualified Prelude
+
+-- | Send an analytics event. Opens a child tracing span named
+-- @analytics.track@, attaches the JSON payload as the span's details,
+-- and invokes the `LogHandler`'s analytics callback. The callback runs
+-- as a `Task` with the current `LogHandler`, so any errors it logs flow
+-- through the normal observability pipeline.
+trackEvent :: (Aeson.ToJSON e) => e -> Task err ()
+trackEvent event =
+  let value = Aeson.toJSON event
+   in Platform.tracingSpan "analytics.track" <| do
+        Platform.setTracingSpanDetails (AnalyticsEventDetails value)
+        Internal.Task
+          ( \handler -> do
+              let Internal.Task runCallback = Internal.trackAnalyticsEvent handler value
+              _ <- runCallback handler
+              Prelude.pure (Ok ())
+          )
+
+-- | A `TracingSpanDetails` wrapper around the analytics event payload, so
+-- that the JSON we send to the analytics backend is also attached to the
+-- @analytics.track@ span and visible in the existing observability
+-- reporters.
+newtype AnalyticsEventDetails = AnalyticsEventDetails Aeson.Value
+  deriving (Aeson.ToJSON)
+
+instance Internal.TracingSpanDetails AnalyticsEventDetails