diff --git a/HoneycombTraceExample.png b/HoneycombTraceExample.png new file mode 100644 Binary files /dev/null and b/HoneycombTraceExample.png differ diff --git a/core-telemetry.cabal b/core-telemetry.cabal --- a/core-telemetry.cabal +++ b/core-telemetry.cabal @@ -1,11 +1,11 @@ -cabal-version: 1.12 +cabal-version: 1.18 -- This file has been generated from package.yaml by hpack version 0.34.4. -- -- see: https://github.com/sol/hpack name: core-telemetry -version: 0.1.7.0 +version: 0.1.7.1 synopsis: Advanced telemetry description: This is part of a library to help build command-line programs, both tools and longer-running daemons. @@ -29,6 +29,8 @@ build-type: Simple tested-with: GHC == 8.10.7 +extra-doc-files: + HoneycombTraceExample.png source-repository head type: git @@ -38,6 +40,7 @@ exposed-modules: Core.Telemetry Core.Telemetry.Console + Core.Telemetry.General Core.Telemetry.Honeycomb Core.Telemetry.Observability Core.Telemetry.Structured diff --git a/lib/Core/Telemetry.hs b/lib/Core/Telemetry.hs --- a/lib/Core/Telemetry.hs +++ b/lib/Core/Telemetry.hs @@ -26,11 +26,13 @@ -- | -- Processors to export telemetry to a backend. module Core.Telemetry.Console, + module Core.Telemetry.General, module Core.Telemetry.Honeycomb, module Core.Telemetry.Structured ) where import Core.Telemetry.Console +import Core.Telemetry.General import Core.Telemetry.Honeycomb import Core.Telemetry.Observability import Core.Telemetry.Structured diff --git a/lib/Core/Telemetry/General.hs b/lib/Core/Telemetry/General.hs new file mode 100644 --- /dev/null +++ b/lib/Core/Telemetry/General.hs @@ -0,0 +1,15 @@ +{-# LANGUAGE OverloadedStrings #-} + +{- | +A generic exporter that may someday send metrics to an OpenTelemetry backend. + +/unimplemented/ +-} +module Core.Telemetry.General ( + generalExporter, +) where + +import Core.Program.Context + +generalExporter :: Exporter +generalExporter = undefined diff --git a/lib/Core/Telemetry/Honeycomb.hs b/lib/Core/Telemetry/Honeycomb.hs --- a/lib/Core/Telemetry/Honeycomb.hs +++ b/lib/Core/Telemetry/Honeycomb.hs @@ -16,12 +16,16 @@ \$ burger-service --telemetry=honeycomb --dataset=prod-restaurant-001 @ +If you annotate your program with spans, you can get a trace like this: + +![Example Trace](HoneycombTraceExample.png) + /Notice/ This library is Open Source but the Honeycomb service is /not/. Honeycomb offers a free tier which is quite suitable for individual use and small local -applications. You can also look at "Core.Telemetry.Other" if you instead want -to forward to a generic OpenTelemetry provider. There's also +applications. You can also look at "Core.Telemetry.General" if you instead +want to forward to a generic OpenTelemetry provider. There's also "Core.Telemetry.Console" which simply dumps telemetry to console. -} module Core.Telemetry.Honeycomb ( diff --git a/lib/Core/Telemetry/Observability.hs b/lib/Core/Telemetry/Observability.hs --- a/lib/Core/Telemetry/Observability.hs +++ b/lib/Core/Telemetry/Observability.hs @@ -36,19 +36,19 @@ main :: 'IO' () main = do context <- 'Core.Program.Execute.configure' \"1.0\" 'Core.Program.Execute.None' ('simpleConfig' []) - context' <- 'initializeTelemetry' ['Core.Telemetry.Console.consoleExporter', 'Core.Telemetry.Console.structuredExporter', 'Core.Telemetry.Console.honeycombExporter'] context + context' <- 'initializeTelemetry' ['Core.Telemetry.Console.consoleExporter', 'Core.Telemetry.Structured.structuredExporter', 'Core.Telemetry.Honeycomb.honeycombExporter'] context 'Core.Program.Execute.executeWith' context' program @ Then when you run your program you can pick the exporter: @ -\$ __burgerservice --telemetry=console__ +\$ __burgerservice --telemetry=structured__ @ -to activate sending telemetry to, in this case, the console. Other exporters -add additional command-line options with which to configure how and where the -metrics will be sent. +to activate sending telemetry, in this case, to the console in the form of +structured JSON logs. Other exporters add additional command-line options with +which to configure how and where the metrics will be sent. = Traces and Spans @@ -109,12 +109,12 @@ In other circumstances you will just want to send metrics: @ - -- not again! - 'sendEvent' \"Cat meowed\" - [ 'metric' \"room\" (\"living room\" :: 'Rope') - , 'metric' "volume\" (127.44 :: 'Float') -- decibels - , 'metric' \"apparently_hungry\" 'True' - ] + -- not again! + 'sendEvent' \"Cat meowed\" + [ 'metric' \"room\" (\"living room\" :: 'Rope') + , 'metric' "volume\" (127.44 :: 'Float') -- decibels + , 'metric' \"apparently_hungry\" 'True' + ] @ will result in @room=\"living room\"@, @volume=127.44@, and @@ -295,7 +295,7 @@ This will allow you to then select the appropriate backend at runtime: @ -\$ __burgerservice --telemetry=structured__ +\$ __burgerservice --telemetry=console__ @ which will result in it spitting out metrics as it goes, @@ -521,12 +521,12 @@ Add measurements to the current span. @ - 'telemetry' - [ 'metric' \"calories\" (667 :: 'Int') - , 'metric' \"precise\" measurement - , 'metric' \"meal_name\" ("hamburger" :: 'Rope') - , 'metric' \"flavour\" 'True' - ] + 'telemetry' + [ 'metric' \"calories\" (667 :: 'Int') + , 'metric' \"precise\" measurement + , 'metric' \"meal_name\" ("hamburger" :: 'Rope') + , 'metric' \"flavour\" 'True' + ] @ The 'metric' function is a method provided by instances of the 'Telemtetry' @@ -571,14 +571,14 @@ If you do call 'sendEvent' within an enclosing span created with 'encloseSpan' (the usual and expected use case) then this event will be \"linked\" to this -span so that the observability tool can deisplay it attached to the span in +span so that the observability tool can display it attached to the span in the in which it occured. @ - 'sendEvent' - "Make tea" - [ 'metric' \"sugar\" 'False' - ] + 'sendEvent' + "Make tea" + [ 'metric' \"sugar\" 'False' + ] @ -} sendEvent :: Label -> [MetricValue] -> Program τ ()