Laws

sanitizeName now keeps the first 15 chars plus a 3-hex hash suffix
for names longer than 19 chars (rrdtool's hard limit on DS name
length). The previous replace-dots-only version produced names up to
31 chars, which rrdtool rejected with 'invalid DS format'.

default.nix

@@ -1,6 +1,7 @@
 { mkDerivation, aeson, annotated-exception, async, base, bytestring
-, containers, hedgehog, hspec, hspec-hedgehog, katip, lens
+, containers, directory, ekg-core, hedgehog, hspec, hspec-hedgehog
-, lens-aeson, lib, network, stm, text, time, uuid, websockets
+, katip, lens, lens-aeson, lib, network, process, stm, text, time
+, unordered-containers, uuid, websockets
 }:
 mkDerivation {
   pname = "home-assistant-controller";
@@ -9,13 +10,15 @@ mkDerivation {
   isLibrary = true;
   isExecutable = true;
   libraryHaskellDepends = [
-    aeson annotated-exception async base bytestring containers katip
+    aeson annotated-exception async base bytestring containers
-    lens lens-aeson network stm text time uuid websockets
+    directory ekg-core katip lens lens-aeson network process stm text
+    time unordered-containers uuid websockets
   ];
   executableHaskellDepends = [ base ];
   testHaskellDepends = [
-    aeson annotated-exception async base containers hedgehog hspec
+    aeson annotated-exception async base containers directory ekg-core
-    hspec-hedgehog katip stm text time uuid
+    hedgehog hspec hspec-hedgehog katip process stm text time
+    unordered-containers uuid
   ];
   license = lib.meta.getLicenseFromSpdxId "BSD-3-Clause";
   mainProgram = "home-assistant-controller";

flake.nix

@@ -20,7 +20,15 @@
       });
     });
     in rec {
-      packages.home-assistant-controller = pkgs.haskell.lib.justStaticExecutables hp.home-assistant-controller;
+      packages.home-assistant-controller = pkgs.symlinkJoin {
+        name = "home-assistant-controller";
+        paths = [ (pkgs.haskell.lib.justStaticExecutables hp.home-assistant-controller) ];
+        nativeBuildInputs = [ pkgs.makeWrapper ];
+        postBuild = ''
+          wrapProgram $out/bin/home-assistant-controller \
+            --set HA_RRDTOOL ${pkgs.lib.getBin pkgs.rrdtool}/bin/rrdtool
+        '';
+      };
       defaultPackage = packages.home-assistant-controller;
       devShell = hp.shellFor {
         packages = h: [h.home-assistant-controller];
@@ -34,6 +42,8 @@
           hp.graphmod
 
           hp.haskell-language-server
+
+          rrdtool
         ];
       };
     }

home-assistant-controller.cabal

@@ -67,6 +67,7 @@ library
                     , HomeAssistant.Runtime
                     , HomeAssistant.Runtime.Bus
                     , HomeAssistant.Runtime.Connection
+                    , HomeAssistant.Runtime.Metrics
                     , HomeAssistant.Runtime.Supervisor
 
     -- Modules included in this library but not exported.
@@ -91,6 +92,10 @@ library
                     , uuid
                     , katip
                     , containers
+                    , ekg-core
+                    , unordered-containers
+                    , process
+                    , directory
 
     -- Directories containing source files.
     hs-source-dirs:   src
@@ -121,7 +126,7 @@ executable home-assistant-controller
 
     -- Base language which the package is written in.
     default-language: GHC2024
-    ghc-options: -threaded
+    ghc-options: -threaded -with-rtsopts=-T
 
 test-suite home-assistant-controller-test
     -- Import common warning flags.
@@ -131,11 +136,13 @@ test-suite home-assistant-controller-test
     default-language: GHC2024
 
     -- Modules included in this executable, other than Main.
-    other-modules:    AFRPSpec
+    other-modules:    AFRPLawsSpec
+                    , AFRPSpec
                     , BackoffProp
                     , BedroomSpec
                     , BusSpec
                     , ConnectionSpec
+                    , MetricsSpec
                     , RuntimeSpec
                     , SupervisorSpec
                     , Support
@@ -167,4 +174,8 @@ test-suite home-assistant-controller-test
         time,
         uuid,
         katip,
-        containers
+        containers,
+        ekg-core,
+        unordered-containers,
+        process,
+        directory

src/HomeAssistant/Runtime.hs

@@ -34,6 +34,9 @@ import Control.Monad.IO.Class (liftIO, MonadIO)
 import Control.Monad.Fix (MonadFix)
 import HomeAssistant.Controller.Ruuvi (ruuviController)
 import HomeAssistant.Controller.Children (schoolLightController)
+import Data.Maybe (fromMaybe)
+import qualified System.Metrics
+import qualified HomeAssistant.Runtime.Metrics
 
 step :: (MonadFix m, MonadIO m) => (forall x. eff x -> m x) -> UUID -> Mealy eff a b -> a -> m (Pair b (Mealy eff a b))
 step nt trace (Mealy _ f) a = do
@@ -74,12 +77,17 @@ defaultMain = withSocketsDo $ do
   withBus severity $ \bus -> do
     token <- getEnv "HA_TOKEN"
     host <- getEnv "HA_HOST"
+    store <- System.Metrics.newStore
+    System.Metrics.registerGcMetrics store
+    rrdPath <- fromMaybe "hass-controller.rrd" <$> lookupEnv "HA_RRD_PATH"
+    rrdtool <- fromMaybe "rrdtool" <$> lookupEnv "HA_RRDTOOL"
     let active = [c | c@(Controller _ _ True) <- controllers]
         ents = foldMap (\(Controller _ m _) -> entities m) active
         workers =
           [ ("reader", readerAction host 8123 token ents bus)
           , ("writer", writerAction bus)
           ] ++ [ (name, runController bus c) | c@(Controller name _ True) <- controllers ]
+            ++ [("metrics", HomeAssistant.Runtime.Metrics.metricsAction store rrdPath rrdtool)]
     as <- mapM (\(name, act) -> async (supervised name defaultBackoff act)) workers
     (_, v) <- waitAny as
     absurd v

src/HomeAssistant/Runtime/Metrics.hs

@@ -0,0 +1,119 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module HomeAssistant.Runtime.Metrics
+  ( DsType (..)
+  , DsSpec (..)
+  , dsTypeOf
+  , sanitizeName
+  , buildSchema
+  , buildCreateArgs
+  , buildUpdateArgs
+  , ensureRrd
+  , sampleAndUpdate
+  , metricsAction
+  ) where
+
+import Control.Concurrent (threadDelay)
+import Control.Monad (forever, unless)
+import Data.Char (ord)
+import Data.Int (Int64)
+import Data.List (intercalate, sortBy)
+import Data.Ord (comparing)
+import Data.Text (Text)
+import Data.Void (Void)
+import Numeric (showHex)
+import qualified Data.Text as T
+import qualified Data.HashMap.Strict as HM
+import qualified System.Metrics as M (Value (..), Sample, Store, sampleAll)
+import System.Directory (doesFileExist)
+import System.Process (callProcess)
+
+data DsType = Derive | Gauge
+  deriving (Eq, Show)
+
+data DsSpec = DsSpec
+  { dsEkgName :: Text
+  , dsName    :: String
+  , dsType    :: DsType
+  }
+  deriving (Eq, Show)
+
+dsTypeOf :: M.Value -> Maybe DsType
+dsTypeOf (M.Counter _) = Just Derive
+dsTypeOf (M.Gauge _)   = Just Gauge
+dsTypeOf _             = Nothing
+
+-- | Maps an ekg metric label to a valid rrd DS name (≤19 chars, [A-Za-z0-9_]).
+-- Long names keep the first 15 chars plus a 3-hex hash suffix for uniqueness.
+sanitizeName :: Text -> String
+sanitizeName name
+  | length sanitized <= 19 = sanitized
+  | otherwise = take 15 sanitized ++ "_" ++ paddedHash
+  where
+    sanitized = T.unpack (T.replace "." "_" name)
+    paddedHash = let h = showHex (sum (map ord sanitized) `mod` 4096) ""
+                 in replicate (3 - length h) '0' ++ h
+
+buildSchema :: M.Sample -> [DsSpec]
+buildSchema sample =
+  sortBy (comparing dsName)
+    [ DsSpec ekgName (sanitizeName ekgName) dt
+    | (ekgName, val) <- HM.toList sample
+    , Just dt <- [dsTypeOf val]
+    ]
+
+buildCreateArgs :: FilePath -> Int -> [(String, DsType)] -> [String]
+buildCreateArgs path step specs =
+  ["create", path, "--step", show step]
+  ++ concatMap dsArg specs
+  ++ rras
+  where
+    dsArg (name, Derive) = ["DS:" ++ name ++ ":DERIVE:20:0:U"]
+    dsArg (name, Gauge)  = ["DS:" ++ name ++ ":GAUGE:20:0:U"]
+    rras =
+      [ "RRA:AVERAGE:0.5:1:6000"
+      , "RRA:MAX:0.5:1:6000"
+      , "RRA:AVERAGE:0.5:360:1680"
+      , "RRA:MAX:0.5:360:1680"
+      ]
+
+buildUpdateArgs :: FilePath -> [String] -> [Maybe Int64] -> [String]
+buildUpdateArgs path names values =
+  [ "update"
+  , path
+  , "--template"
+  , intercalate ":" names
+  , "N:" ++ intercalate ":" (map renderValue values)
+  ]
+  where
+    renderValue Nothing  = "U"
+    renderValue (Just n) = show n
+
+lookupValue :: M.Sample -> Text -> Maybe Int64
+lookupValue sample name = case HM.lookup name sample of
+  Just (M.Counter n) -> Just n
+  Just (M.Gauge n)   -> Just n
+  _                  -> Nothing
+
+ensureRrd :: FilePath -> FilePath -> [DsSpec] -> IO ()
+ensureRrd rrdtool rrdPath schema = do
+  exists <- doesFileExist rrdPath
+  unless exists $
+    callProcess rrdtool (buildCreateArgs rrdPath 10 (map toPair schema))
+  where
+    toPair s = (dsName s, dsType s)
+
+sampleAndUpdate :: M.Store -> FilePath -> FilePath -> [DsSpec] -> IO ()
+sampleAndUpdate store rrdtool rrdPath schema = do
+  sample <- M.sampleAll store
+  let names = map dsName schema
+      values = map (lookupValue sample . dsEkgName) schema
+  callProcess rrdtool (buildUpdateArgs rrdPath names values)
+
+metricsAction :: M.Store -> FilePath -> FilePath -> IO Void
+metricsAction store rrdPath rrdtool = do
+  schema <- buildSchema <$> M.sampleAll store
+  ensureRrd rrdtool rrdPath schema
+  forever $ do
+    sampleAndUpdate store rrdtool rrdPath schema
+    threadDelay 10000000

test/AFRPLawsSpec.hs

@@ -0,0 +1,254 @@
+module AFRPLawsSpec (spec) where
+
+import AFRP
+import Control.Arrow (arr, first, left, (***), (+++))
+import Control.Category ((>>>))
+import qualified Control.Category as Cat (id)
+import Data.Functor.Identity (Identity (..))
+import Hedgehog (Gen, PropertyT)
+import qualified Hedgehog.Gen as Gen
+import qualified Hedgehog.Range as Range
+import Support (fakeRequest)
+import Test.Hspec (Spec, describe, it)
+import Test.Hspec.Hedgehog (forAll, forAllWith, hedgehog, (===))
+
+-- | Law tests for the Mealy instances. Two machines count as equal when
+-- they emit equal outputs on every input sequence, so each law runs both
+-- sides on generated inputs.
+
+runPure :: Mealy Identity a b -> [a] -> [b]
+runPure _ [] = []
+runPure m (a : as) = case runIdentity (runMealy m id fakeRequest a) of
+  Pair b m' -> b : runPure m' as
+
+-- | Machines wrap functions and have no Show; name them for forAll instead.
+forAllMealy :: Gen (Mealy Identity a b) -> PropertyT IO (Mealy Identity a b)
+forAllMealy = forAllWith (const "<mealy>")
+
+intGen :: Gen Int
+intGen = Gen.int (Range.linear (-5) 5)
+
+ints :: Gen [Int]
+ints = Gen.list (Range.linear 0 30) intGen
+
+intPairs :: Gen [(Int, Int)]
+intPairs = Gen.list (Range.linear 0 30) ((,) <$> intGen <*> intGen)
+
+intEithers :: Gen [Either Int Int]
+intEithers = Gen.list (Range.linear 0 30) $
+  Gen.choice [Left <$> intGen, Right <$> intGen]
+
+nestedPairs :: Gen [((Int, Int), Int)]
+nestedPairs = Gen.list (Range.linear 0 30) ((,) <$> ((,) <$> intGen <*> intGen) <*> intGen)
+
+nestedEithers :: Gen [Either (Either Int Int) Int]
+nestedEithers = Gen.list (Range.linear 0 30) $
+  Gen.choice
+    [ Left <$> Gen.choice [Left <$> intGen, Right <$> intGen]
+    , Right <$> intGen
+    ]
+
+-- | Stateful Int machines: the arrow variables of the laws.
+statefulGen :: Gen (Mealy Identity Int Int)
+statefulGen = Gen.choice
+  [ (\k -> mapAccum (+) k id) <$> intGen
+  , (\k -> preMapAccum (+) k id) <$> intGen
+  , (\k -> mapAccum (*) 1 (+ k)) <$> intGen
+  ]
+
+eventArrowGen :: Gen (Mealy Identity Int (Event Int))
+eventArrowGen = Gen.choice
+  [ pure changes
+  , (\k -> mapAccum (+) k Event) <$> intGen
+  , (\k -> preMapAccum (+) k (Event . (* 2))) <$> intGen
+  ]
+
+funArrowGen :: Gen (Mealy Identity Int (Int -> Int))
+funArrowGen = Gen.choice
+  [ (\k -> mapAccum (+) k (*)) <$> intGen
+  , pure (preMapAccum (*) 1 (+))
+  ]
+
+spec :: Spec
+spec = describe "Mealy laws" $ do
+  semigroupSpec
+  monoidSpec
+  categorySpec
+  arrowSpec
+  arrowChoiceSpec
+  functorSpec
+  applicativeSpec
+
+semigroupSpec :: Spec
+semigroupSpec = describe "Semigroup (<>)" $ do
+  it "(a <> b) <> c = a <> (b <> c)" $ hedgehog $ do
+    a <- forAllMealy eventArrowGen
+    b <- forAllMealy eventArrowGen
+    c <- forAllMealy eventArrowGen
+    xs <- forAll ints
+    runPure ((a <> b) <> c) xs === runPure (a <> (b <> c)) xs
+
+monoidSpec :: Spec
+monoidSpec = describe "Monoid" $ do
+  it "mempty <> a = a" $ hedgehog $ do
+    a <- forAllMealy eventArrowGen
+    xs <- forAll ints
+    runPure (mempty <> a) xs === runPure a xs
+
+  it "a <> mempty = a" $ hedgehog $ do
+    a <- forAllMealy eventArrowGen
+    xs <- forAll ints
+    runPure (a <> mempty) xs === runPure a xs
+
+categorySpec :: Spec
+categorySpec = describe "Category" $ do
+  it "id >>> f = f" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    xs <- forAll ints
+    runPure (Cat.id >>> f) xs === runPure f xs
+
+  it "f >>> id = f" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    xs <- forAll ints
+    runPure (f >>> Cat.id) xs === runPure f xs
+
+  it "(f >>> g) >>> h = f >>> (g >>> h)" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    g <- forAllMealy statefulGen
+    h <- forAllMealy statefulGen
+    xs <- forAll ints
+    runPure ((f >>> g) >>> h) xs === runPure (f >>> (g >>> h)) xs
+
+arrowSpec :: Spec
+arrowSpec = describe "Arrow" $ do
+  it "arr id = id" $ hedgehog $ do
+    xs <- forAll ints
+    runPure (arr id :: Mealy Identity Int Int) xs === runPure Cat.id xs
+
+  it "arr (f >>> g) = arr f >>> arr g" $ hedgehog $ do
+    p <- forAll intGen
+    q <- forAll intGen
+    xs <- forAll ints
+    let f = (+ p)
+        g = (* q)
+    runPure (arr (f >>> g)) xs === runPure (arr f >>> arr g) xs
+
+  it "first (arr f) = arr (first f)" $ hedgehog $ do
+    p <- forAll intGen
+    ps <- forAll intPairs
+    let f = (+ p)
+    runPure (first (arr f)) ps === runPure (arr (first f)) ps
+
+  it "first (f >>> g) = first f >>> first g" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    g <- forAllMealy statefulGen
+    ps <- forAll intPairs
+    runPure (first (f >>> g)) ps === runPure (first f >>> first g) ps
+
+  it "first f >>> arr fst = arr fst >>> f" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    ps <- forAll intPairs
+    runPure (first f >>> arr fst) ps === runPure (arr fst >>> f) ps
+
+  it "first f >>> arr (id *** g) = arr (id *** g) >>> first f" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    p <- forAll intGen
+    ps <- forAll intPairs
+    let g = (* p)
+    runPure (first f >>> arr (id *** g)) ps
+      === runPure (arr (id *** g) >>> first f) ps
+
+  it "first (first f) >>> arr assoc = arr assoc >>> first f" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    ts <- forAll nestedPairs
+    let assoc ((a, b), c) = (a, (b, c))
+    runPure (first (first f) >>> arr assoc) ts
+      === runPure (arr assoc >>> first f) ts
+
+arrowChoiceSpec :: Spec
+arrowChoiceSpec = describe "ArrowChoice" $ do
+  it "left (arr f) = arr (left f)" $ hedgehog $ do
+    p <- forAll intGen
+    es <- forAll intEithers
+    let f = (+ p)
+    runPure (left (arr f)) es === runPure (arr (left f)) es
+
+  it "left (f >>> g) = left f >>> left g" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    g <- forAllMealy statefulGen
+    es <- forAll intEithers
+    runPure (left (f >>> g)) es === runPure (left f >>> left g) es
+
+  it "f >>> arr Left = arr Left >>> left f" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    xs <- forAll ints
+    runPure (f >>> arr (Left @Int @Int)) xs
+      === runPure (arr (Left @Int @Int) >>> left f) xs
+
+  it "left f >>> arr (id +++ g) = arr (id +++ g) >>> left f" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    p <- forAll intGen
+    es <- forAll intEithers
+    let g = (* p)
+    runPure (left f >>> arr (id +++ g)) es
+      === runPure (arr (id +++ g) >>> left f) es
+
+  it "left (left f) >>> arr assocsum = arr assocsum >>> left f" $ hedgehog $ do
+    f <- forAllMealy statefulGen
+    es <- forAll nestedEithers
+    let assocsum (Left (Left x)) = Left x
+        assocsum (Left (Right y)) = Right (Left y)
+        assocsum (Right z) = Right (Right z)
+    runPure (left (left f) >>> arr assocsum) es
+      === runPure (arr assocsum >>> left f) es
+
+functorSpec :: Spec
+functorSpec = describe "Functor" $ do
+  it "fmap id = id" $ hedgehog $ do
+    m <- forAllMealy statefulGen
+    xs <- forAll ints
+    runPure (fmap id m) xs === runPure m xs
+
+  it "fmap (f . g) = fmap f . fmap g" $ hedgehog $ do
+    m <- forAllMealy statefulGen
+    p <- forAll intGen
+    q <- forAll intGen
+    xs <- forAll ints
+    let f = (+ p)
+        g = (* q)
+    runPure (fmap (f . g) m) xs === runPure (fmap f (fmap g m)) xs
+
+applicativeSpec :: Spec
+applicativeSpec = describe "Applicative" $ do
+  it "pure id <*> v = v" $ hedgehog $ do
+    v <- forAllMealy statefulGen
+    xs <- forAll ints
+    runPure (pure id <*> v) xs === runPure v xs
+
+  it "pure f <*> pure x = pure (f x)" $ hedgehog $ do
+    p <- forAll intGen
+    x <- forAll intGen
+    xs <- forAll ints
+    let f = (+ p)
+    runPure (pure f <*> pure x) xs === runPure (pure (f x)) xs
+
+  it "u <*> pure y = pure ($ y) <*> u" $ hedgehog $ do
+    u <- forAllMealy funArrowGen
+    y <- forAll intGen
+    xs <- forAll ints
+    runPure (u <*> pure y) xs === runPure (pure ($ y) <*> u) xs
+
+  it "pure (.) <*> u <*> v <*> w = u <*> (v <*> w)" $ hedgehog $ do
+    u <- forAllMealy funArrowGen
+    v <- forAllMealy funArrowGen
+    w <- forAllMealy statefulGen
+    xs <- forAll ints
+    runPure (pure (.) <*> u <*> v <*> w) xs
+      === runPure (u <*> (v <*> w)) xs
+
+  it "fmap f x = pure f <*> x" $ hedgehog $ do
+    x <- forAllMealy statefulGen
+    p <- forAll intGen
+    xs <- forAll ints
+    let f = (+ p)
+    runPure (fmap f x) xs === runPure (pure f <*> x) xs

test/Main.hs

@@ -1,20 +1,24 @@
 module Main (main) where
 
 import Test.Hspec (hspec)
+import qualified AFRPLawsSpec
 import qualified AFRPSpec
 import qualified BackoffProp
 import qualified BedroomSpec
 import qualified BusSpec
 import qualified ConnectionSpec
+import qualified MetricsSpec
 import qualified RuntimeSpec
 import qualified SupervisorSpec
 
 main :: IO ()
 main = hspec $ do
+  AFRPLawsSpec.spec
   AFRPSpec.spec
   BedroomSpec.spec
   BusSpec.spec
   ConnectionSpec.spec
+  MetricsSpec.spec
   RuntimeSpec.spec
   SupervisorSpec.spec
   BackoffProp.spec

test/MetricsSpec.hs

@@ -0,0 +1,150 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module MetricsSpec (spec) where
+
+import Data.HashMap.Strict (HashMap)
+import qualified Data.HashMap.Strict as HM
+import Data.Int (Int64)
+import Data.Text (Text)
+import HomeAssistant.Runtime.Metrics
+  ( DsType (..)
+  , DsSpec (..)
+  , dsTypeOf
+  , sanitizeName
+  , buildSchema
+  , buildCreateArgs
+  , buildUpdateArgs
+  , ensureRrd
+  , sampleAndUpdate
+  , metricsAction
+  )
+import qualified System.Metrics as M (Value (..))
+import Test.Hspec
+import Control.Exception (try, SomeException)
+import System.Directory (findExecutable, getTemporaryDirectory, removeFile)
+import System.Exit (ExitCode (ExitSuccess))
+import System.Process (readProcessWithExitCode)
+import qualified System.Metrics as Metrics
+import qualified System.Metrics.Counter as Counter
+import qualified System.Metrics.Gauge as Gauge
+
+spec :: Spec
+spec = do
+  describe "dsTypeOf" $ do
+    it "maps Counter to Derive" $
+      dsTypeOf (M.Counter 1000) `shouldBe` Just Derive
+
+    it "maps Gauge to Gauge" $
+      dsTypeOf (M.Gauge 500) `shouldBe` Just Gauge
+
+    it "maps Label to Nothing" $
+      dsTypeOf (M.Label "hello") `shouldBe` Nothing
+
+  describe "sanitizeName" $ do
+    it "replaces dots with underscores for short names" $
+      sanitizeName ("rts.gc.cpu_ms" :: Text) `shouldBe` "rts_gc_cpu_ms"
+
+    it "shortens names longer than 19 chars to 15 chars + _ + 3 hex" $ do
+      let result = sanitizeName ("rts.gc.par_balanced_bytes_copied" :: Text)
+      length result `shouldBe` 19
+      take 15 result `shouldBe` "rts_gc_par_bala"
+      drop 15 result `shouldBe` "_" ++ drop 16 result
+
+    it "is deterministic (same input -> same output)" $
+      sanitizeName ("rts.gc.peak_megabytes_allocated" :: Text)
+        `shouldBe` sanitizeName ("rts.gc.peak_megabytes_allocated" :: Text)
+
+  describe "buildSchema" $ do
+    it "builds sorted DsSpecs from counters and gauges, skipping labels" $
+      let sample :: HashMap Text M.Value
+          sample = HM.fromList
+            [ ("x.allocated", M.Counter 1000)
+            , ("a.bytes_used", M.Gauge 500)
+            , ("c.label_thing", M.Label "irrelevant")
+            ]
+      in buildSchema sample `shouldBe`
+           [ DsSpec "a.bytes_used" "a_bytes_used" Gauge
+           , DsSpec "x.allocated" "x_allocated" Derive
+           ]
+
+    it "produces dsName <= 19 chars for long ekg GC metric names" $
+      let sample :: HashMap Text M.Value
+          sample = HM.fromList
+            [ ("rts.gc.par_balanced_bytes_copied", M.Gauge 1)
+            , ("rts.gc.peak_megabytes_allocated", M.Gauge 2)
+            , ("rts.gc.cumulative_bytes_used", M.Counter 3)
+            ]
+      in map (length . dsName) (buildSchema sample) `shouldSatisfy` all (<= 19)
+
+  describe "buildCreateArgs" $ do
+    it "builds create argv with mixed DERIVE and GAUGE DSes and RRAs" $
+      buildCreateArgs "test.rrd" 10
+        [ ("ds1", Derive)
+        , ("ds2", Gauge)
+        ]
+        `shouldBe`
+          [ "create"
+          , "test.rrd"
+          , "--step"
+          , "10"
+          , "DS:ds1:DERIVE:20:0:U"
+          , "DS:ds2:GAUGE:20:0:U"
+          , "RRA:AVERAGE:0.5:1:6000"
+          , "RRA:MAX:0.5:1:6000"
+          , "RRA:AVERAGE:0.5:360:1680"
+          , "RRA:MAX:0.5:360:1680"
+          ]
+
+  describe "buildUpdateArgs" $ do
+    it "builds update argv with numeric values" $
+      buildUpdateArgs "test.rrd" ["ds1", "ds2"] [Just 100, Just 200]
+        `shouldBe`
+          [ "update"
+          , "test.rrd"
+          , "--template"
+          , "ds1:ds2"
+          , "N:100:200"
+          ]
+
+    it "renders Nothing as U (unknown)" $
+      buildUpdateArgs "test.rrd" ["ds1", "ds2"] [Just 100, Nothing]
+        `shouldBe`
+          [ "update"
+          , "test.rrd"
+          , "--template"
+          , "ds1:ds2"
+          , "N:100:U"
+          ]
+
+    it "renders all-Nothing as all-U" $
+      buildUpdateArgs "test.rrd" ["ds1"] [Nothing]
+        `shouldBe`
+          [ "update"
+          , "test.rrd"
+          , "--template"
+          , "ds1"
+          , "N:U"
+          ]
+
+  describe "end-to-end (rrdtool-gated)" $ do
+    it "creates an rrd, samples, and updates it" $ do
+      mRrdtool <- findExecutable "rrdtool"
+      case mRrdtool of
+        Nothing -> pendingWith "rrdtool not on PATH"
+        Just rrdtool -> do
+          store <- Metrics.newStore
+          c <- Metrics.createCounter "test.counter" store
+          g <- Metrics.createGauge "test.gauge" store
+          Counter.inc c
+          Gauge.set g 42
+          tmp <- getTemporaryDirectory
+          let rrdPath = tmp ++ "/hass-controller-metrics-test.rrd"
+          _ <- try (removeFile rrdPath) :: IO (Either SomeException ())
+          schema <- buildSchema <$> Metrics.sampleAll store
+          ensureRrd rrdtool rrdPath schema
+          sampleAndUpdate store rrdtool rrdPath schema
+          (rc, out, _) <- readProcessWithExitCode rrdtool ["fetch", rrdPath, "AVERAGE"] ""
+          rc `shouldBe` ExitSuccess
+          length out `shouldSatisfy` (> 0)
+          _ <- try (removeFile rrdPath) :: IO (Either SomeException ())
+          return ()