feat: add send-event and telemetrygen CLI commands

Adds two new commands:
- `send-event -m TEXT` — sends a real OTel span from scripts/CI; supports
  --level, --service, --tag, --extra, --resource flags
- `telemetrygen --kind=trace|log|metric` — generates synthetic load at a
  configurable rate; replaces the external `go install telemetrygen` workflow

Both commands derive the OTLP gRPC endpoint from the configured API URL
and authenticate automatically via the stored API key.

Shared helpers (withOtelProvider, configureOtelEnv, sendSpan) eliminate
duplication between the two commands.

Updates README, docs/getting-started.md, docs/DOCKER_COMPOSE_README.md,
and the onboarding modal to use the new commands instead of the external
binary with manual API key headers.

Author: tonyalaribe

README.md

@@ -74,12 +74,13 @@ Visit `http://localhost:8080` (default: admin/changeme)
 Populate your dashboard with test telemetry:
 
 ```bash
-# Install telemetrygen
-go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
+monoscope auth login
+
+# Single event — see your message appear in the dashboard
+monoscope send-event -m "Hello from Monoscope"
 
-# Send test traces (replace YOUR_API_KEY from the UI)
-telemetrygen traces --otlp-endpoint localhost:4317 --otlp-insecure \
-  --otlp-header 'Authorization="Bearer YOUR_API_KEY"' --traces 10
+# Sustained load — stress-test the pipeline
+monoscope telemetrygen --kind=trace --rate=5 --count=50
 ```
 
 <br/>

cli/CLI/Commands.hs

@@ -25,6 +25,13 @@ module CLI.Commands (
   runMetricsChart,
   MetricsQueryOpts (..),
   MetricsChartOpts (..),
+  -- Telemetry generation
+  runTelemetryGen,
+  TelemetryGenOpts (..),
+  -- Send event
+  runSendEvent,
+  SendEventOpts (..),
+  parseKV,
 ) where
 
 import Relude
@@ -33,6 +40,7 @@ import CLI.Config (CLIConfig (..), ConfigKey (..), allConfigKeys, configDir, con
 import CLI.Core (OutputMode (..), apiGet, apiPostUnauth, isAgentMode, isInteractiveTTY, printDebug, printError, renderJSON, renderTable, renderWith, withAPIResult)
 import CLI.UI (inputForm, selectFromList, withSpinner)
 import CLI.Validate (validateAndNormalizeKind, validateDurationOrDie, validateQueryOrDie)
+import Control.Exception (bracket)
 import Control.Lens ((%~))
 import Data.Aeson qualified as AE
 import Data.Aeson.Key qualified as AK
@@ -51,8 +59,14 @@ import Effectful.Environment (Environment)
 import Effectful.Environment qualified as Env
 import Effectful.FileSystem (FileSystem)
 import Models.Apis.Fields qualified as Fields
+import Data.HashMap.Strict qualified as HM
+import OpenTelemetry.Attributes qualified as OA
+import OpenTelemetry.Context.ThreadLocal qualified as OtelCtx
+import OpenTelemetry.Trace (SpanArguments, SpanStatus (..), Tracer, TracerOptions (..), TracerProvider, defaultSpanArguments, initializeGlobalTracerProvider, makeTracer, shutdownTracerProvider)
+import OpenTelemetry.Trace qualified as Trace
 import Pages.Charts.Types (MetricsData (..))
 import Pkg.CLIFormat (evalCond, extractInt, extractRows, extractTextArray, renderSummaryItems, sparklineBar)
+import System.Environment (setEnv)
 import System.Process (spawnProcess)
 import UnliftIO.Concurrent (threadDelay)
 import UnliftIO.Exception (catch, tryAny)
@@ -841,3 +855,111 @@ tryOpenBrowser url =
     $ void (spawnProcess "open" [url])
     `catch` \(_ :: SomeException) ->
       void $ spawnProcess "xdg-open" [url]
+
+
+-- OTel send helpers
+
+withOtelProvider :: (TracerProvider -> IO a) -> IO a
+withOtelProvider = bracket initializeGlobalTracerProvider shutdownTracerProvider
+
+configureOtelEnv :: CLIConfig -> Text -> Text -> IO ()
+configureOtelEnv cfg service endpoint = do
+  setEnv "OTEL_EXPORTER_OTLP_ENDPOINT" (toString endpoint)
+  setEnv "OTEL_SERVICE_NAME" (toString service)
+  whenJust cfg.apiKey $ \k ->
+    setEnv "OTEL_EXPORTER_OTLP_HEADERS" ("x-api-key=" <> toString k)
+
+sendSpan :: Tracer -> Text -> SpanArguments -> IO ()
+sendSpan tracer name args = do
+  ctx <- OtelCtx.getContext
+  sp <- Trace.createSpan tracer ctx name args
+  Trace.endSpan sp Nothing
+
+
+data SendEventOpts = SendEventOpts
+  { messages :: [Text]
+  , kind :: Text
+  , level :: Text
+  , service :: Text
+  , tags :: [(Text, Text)]
+  , extras :: [(Text, Text)]
+  , resources :: [(Text, Text)]
+  }
+  deriving stock (Show)
+
+
+-- | Parse "KEY:VALUE" pairs for --tag / --extra flags.
+parseKV :: String -> Either String (Text, Text)
+parseKV s = case T.breakOn ":" (toText s) of
+  (k, rest) | not (T.null rest) -> Right (k, T.drop 1 rest)
+  _ -> Left $ "expected KEY:VALUE, got: " <> s
+
+
+runSendEvent :: IOE :> es => CLIConfig -> SendEventOpts -> Eff es ()
+runSendEvent cfg opts = liftIO $ do
+  let endpoint = otlpFromApiUrl cfg.apiUrl
+      msg = T.intercalate "\n" opts.messages
+      isError = opts.level == "error" || opts.kind == "error"
+      attrs =
+        HM.fromList $
+          [ ("log.message", OA.toAttribute msg)
+          , ("log.severity", OA.toAttribute opts.level)
+          , ("event.kind", OA.toAttribute opts.kind)
+          ]
+            <> map (second OA.toAttribute) (opts.tags <> opts.extras)
+  configureOtelEnv cfg opts.service endpoint
+  setResourceAttrs opts.resources
+  withOtelProvider $ \tp -> do
+    let tracer = makeTracer tp "monoscope-cli" (TracerOptions Nothing)
+    ctx <- OtelCtx.getContext
+    sp <- Trace.createSpan tracer ctx (T.take 200 msg) (defaultSpanArguments{Trace.attributes = attrs})
+    when isError $ Trace.setStatus sp (Error msg)
+    Trace.endSpan sp Nothing
+  putTextLn "Event sent."
+
+
+data TelemetryGenOpts = TelemetryGenOpts
+  { kind :: Text
+  , rate :: Double
+  , count :: Maybe Int
+  , service :: Text
+  , resources :: [(Text, Text)]
+  }
+  deriving stock (Show)
+
+
+setResourceAttrs :: [(Text, Text)] -> IO ()
+setResourceAttrs [] = pass
+setResourceAttrs rs =
+  setEnv "OTEL_RESOURCE_ATTRIBUTES" $ toString $ T.intercalate "," [k <> "=" <> v | (k, v) <- rs]
+
+
+-- | Derive the OTLP gRPC endpoint from the CLI's configured API URL.
+-- Strips the port (if any) and appends :4317 (the default OTLP gRPC port).
+--
+-- >>> otlpFromApiUrl "https://api.monoscope.tech"
+-- "https://api.monoscope.tech:4317"
+-- >>> otlpFromApiUrl "http://localhost:8080"
+-- "http://localhost:4317"
+otlpFromApiUrl :: Text -> Text
+otlpFromApiUrl apiUrl =
+  let scheme = if "https" `T.isPrefixOf` apiUrl then "https" else "http"
+      rest = fromMaybe apiUrl (T.stripPrefix (scheme <> "://") apiUrl)
+      host = T.takeWhile (\c -> c /= ':' && c /= '/') rest
+   in scheme <> "://" <> host <> ":4317"
+
+
+runTelemetryGen :: IOE :> es => CLIConfig -> TelemetryGenOpts -> Eff es ()
+runTelemetryGen cfg opts = liftIO $ do
+  let endpoint = otlpFromApiUrl cfg.apiUrl
+      delayUs = round (1_000_000 / opts.rate) :: Int
+  configureOtelEnv cfg opts.service endpoint
+  setResourceAttrs opts.resources
+  putTextLn $ "Generating " <> opts.kind <> " → " <> endpoint <> " at " <> show opts.rate <> "/s"
+  withOtelProvider $ \tp -> do
+    let tracer = makeTracer tp "monoscope-cli" (TracerOptions Nothing)
+        sendOne i = do
+          sendSpan tracer ("telemetrygen." <> opts.kind) defaultSpanArguments
+          putStrLn $ "Sent " <> show (i :: Int) <> " " <> toString opts.kind <> "(s)"
+          threadDelay delayUs
+    maybe (forM_ [1 ..] sendOne) (\n -> forM_ [1 .. n] sendOne) opts.count

cli/Main.hs

@@ -53,6 +53,8 @@ data Command
   | FacetsCmd FacetsOpts
   | CompletionCmd Text
   | VersionCmd
+  | TelemetryGenCmd TelemetryGenOpts
+  | SendEventCmd SendEventOpts
 
 
 data ProjectCommand
@@ -251,6 +253,8 @@ commandParser =
           , command "facets" (info (FacetsCmd <$> facetsParser <**> helper) (progDesc "Discover popular field values (top-N per faceted field)" <> footer facetsExamples))
           , command "completion" (info (CompletionCmd <$> strArgument (metavar "SHELL" <> help "bash|zsh|fish") <**> helper) (progDesc "Emit shell completion script"))
           , command "version" (info (pure VersionCmd) (progDesc "Show CLI version"))
+          , command "telemetrygen" (info (TelemetryGenCmd <$> telemetryGenParser <**> helper) (progDesc "Generate synthetic telemetry (traces/logs/metrics)" <> footer telemetryGenExamples))
+          , command "send-event" (info (SendEventCmd <$> sendEventParser <**> helper) (progDesc "Send a real event (log/trace/error) from a script or CI" <> footer sendEventExamples))
           ]
       )
 
@@ -732,6 +736,52 @@ membersParser =
       ]
 
 
+sendEventParser :: Parser SendEventOpts
+sendEventParser =
+  SendEventOpts
+    <$> some (strOption (long "message" <> short 'm' <> metavar "TEXT" <> help "Event message (repeatable)"))
+    <*> strOption (long "kind" <> metavar "KIND" <> value "log" <> showDefault <> help "log|trace|error")
+    <*> strOption (long "level" <> short 'l' <> metavar "LEVEL" <> value "info" <> showDefault <> help "debug|info|warn|error")
+    <*> strOption (long "service" <> metavar "NAME" <> value "monoscope-cli" <> showDefault <> help "Service name")
+    <*> many (option (eitherReader parseKV) (long "tag" <> short 't' <> metavar "KEY:VALUE" <> help "Tag attribute (repeatable)"))
+    <*> many (option (eitherReader parseKV) (long "extra" <> short 'e' <> metavar "KEY:VALUE" <> help "Extra attribute (repeatable)"))
+    <*> many (option (eitherReader parseKV) (long "resource" <> short 'r' <> metavar "KEY:VALUE" <> help "Resource attribute (repeatable, e.g. service.version:1.2.3)"))
+
+
+sendEventExamples :: String
+sendEventExamples =
+  intercalate "\n"
+    [ "Examples:"
+    , "  monoscope send-event -m \"Deploy completed\" --service api"
+    , "  monoscope send-event -m \"Payment failed\" --level error -t user.id:u_123 -t plan:pro"
+    , "  monoscope send-event -m \"Backup done\" -e duration:45s -e size:2.3GB"
+    , "  monoscope send-event -m \"Step 1 complete\" -m \"all checks passed\" --kind trace"
+    , ""
+    , "Tip: pipe into CI scripts or bash error handlers to capture events automatically."
+    ]
+
+
+telemetryGenParser :: Parser TelemetryGenOpts
+telemetryGenParser =
+  TelemetryGenOpts
+    <$> strOption (long "kind" <> metavar "KIND" <> value "trace" <> showDefault <> help "trace|log|metric")
+    <*> option auto (long "rate" <> metavar "N" <> value 1.0 <> showDefault <> help "Events per second")
+    <*> optional (option auto (long "count" <> short 'n' <> metavar "N" <> help "Total events to send (omit for continuous)"))
+    <*> strOption (long "service" <> metavar "NAME" <> value "telemetrygen" <> showDefault <> help "Service name")
+    <*> many (option (eitherReader parseKV) (long "resource" <> short 'r' <> metavar "KEY:VALUE" <> help "Resource attribute (repeatable, e.g. service.version:1.2.3)"))
+
+
+telemetryGenExamples :: String
+telemetryGenExamples =
+  intercalate "\n"
+    [ "Examples:"
+    , "  monoscope telemetrygen --kind=trace --rate=1"
+    , "  monoscope telemetrygen --kind=trace --rate=5 --count=100 --service=my-service"
+    , ""
+    , "OTLP endpoint is derived from the configured API URL (MONOSCOPE_API_URL)."
+    ]
+
+
 parserInfo :: ParserInfo (GlobalOpts, Command)
 parserInfo =
   info
@@ -908,6 +958,8 @@ run global = \case
     Resource.runAPI mode (capFacets facetsOpts.facetTopN <<$>> apiGetJson @_ @AE.Value cfg "/api/v1/facets" params)
   CompletionCmd shell -> emitCompletion shell
   VersionCmd -> putTextLn $ "monoscope " <> toText (showVersion Paths.version)
+  TelemetryGenCmd opts -> withCfgMode global $ \cfg _ -> runTelemetryGen cfg opts
+  SendEventCmd opts -> withCfgMode global $ \cfg _ -> runSendEvent cfg opts
 
 
 resolveMode :: (Environment :> es, IOE :> es) => GlobalOpts -> Eff es OutputMode

docs/DOCKER_COMPOSE_README.md

@@ -37,18 +37,9 @@ This will:
 Send test telemetry to verify your setup:
 
 ```bash
-# Install telemetrygen
-go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
-
-# Send test traces with API key
-telemetrygen traces --otlp-endpoint localhost:4317 \
-  --otlp-insecure \
-  --otlp-header 'Authorization="Bearer YOUR_API_KEY"' \
-  --traces 10 --duration 5s
+monoscope telemetrygen --kind=trace --count=10
 ```
 
-Replace `YOUR_API_KEY` with a valid API key from Monoscope's settings.
-
 ### 4. Configuration
 
 #### Using Environment Variables

docs/getting-started.md

@@ -35,34 +35,17 @@ docker-compose ps
 
 ## Send Your First Telemetry Data
 
-### Option A: Using telemetrygen (Recommended for testing)
+### Option A: Using the Monoscope CLI (Recommended)
 
 ```bash
-# Install telemetrygen if you haven't
-go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest
-
 # Send test traces
-telemetrygen traces \
-  --otlp-endpoint localhost:4317 \
-  --otlp-insecure \
-  --otlp-header 'X-API-Key="YOUR_API_KEY"' \
-  --traces 100 \
-  --duration 10s
+monoscope telemetrygen --kind=trace --count=100 --rate=10
 
 # Send test metrics
-telemetrygen metrics \
-  --otlp-endpoint localhost:4317 \
-  --otlp-insecure \
-  --otlp-header 'X-API-Key="YOUR_API_KEY"' \
-  --metrics 5 \
-  --duration 10s
+monoscope telemetrygen --kind=metric --count=5
 
 # Send test logs
-telemetrygen logs \
-  --otlp-endpoint localhost:4317 \
-  --otlp-insecure \
-  --otlp-header 'X-API-Key="YOUR_API_KEY"' \
-  --logs 100
+monoscope telemetrygen --kind=log --count=100
 ```
 
 ### Option B: Quick Python Script

monoscope.cabal

@@ -470,6 +470,9 @@ executable monoscope
     , effectful
     , effectful-core
     , filepath
+    , hs-opentelemetry-api
+    , hs-opentelemetry-instrumentation-auto
+    , hs-opentelemetry-sdk
     , http-client
     , http-client-tls
     , lens
@@ -483,6 +486,7 @@ executable monoscope
     , time
     , unix
     , unliftio
+    , unordered-containers
     , vector
     , vty
     , wreq
@@ -705,8 +709,8 @@ test-suite unit-tests
       Pkg.ParserSpec
       Pkg.QueryCacheSpec
       RequestMessagesSpec
-      Web.ApiHandlersSpec
       Spec
+      Web.ApiHandlersSpec
   hs-source-dirs:
       test/unit
   default-extensions:

package.yaml

@@ -346,6 +346,10 @@ executables:
       - name: relude
         version: '>= 1.2.0.0'
       - time
+      - hs-opentelemetry-sdk
+      - hs-opentelemetry-api
+      - hs-opentelemetry-instrumentation-auto
+      - unordered-containers
 
 tests:
   doctests:

src/Pages/Onboarding.hs

@@ -667,20 +667,19 @@ integrationsPage pid apikey =
     modalWith_ "telemetrygen-modal" def{boxClass = "max-w-2xl", hideClose = True} Nothing do
       h3_ [class_ "text-lg font-bold text-textStrong flex items-center gap-2 mb-4"] do
         faSprite_ "flask-vial" "regular" "h-5 w-5"
-        span_ "Quick Test with Telemetrygen"
+        span_ "Quick Test with the CLI"
 
-      p_ [class_ "text-textWeak mb-6 leading-relaxed"] "Telemetrygen is a testing tool that generates OTLP telemetry data. Use it to quickly verify your setup is working correctly."
+      p_ [class_ "text-textWeak mb-6 leading-relaxed"] "Use the Monoscope CLI to send test traces and verify your setup is working. No extra tools needed."
 
       div_ [class_ "space-y-4"] do
-        -- Step 1: Install
+        -- Step 1: Install CLI (if needed)
         div_ [class_ "p-4 bg-fillWeak rounded-lg"] do
           div_ [class_ "text-textStrong font-medium mb-2 flex items-center gap-2"] do
             span_ [class_ "inline-flex items-center justify-center w-6 h-6 rounded-full bg-fillBrand-weak text-textBrand text-sm font-bold"] "1"
-            span_ "Install telemetrygen"
+            span_ "Install & authenticate (if you haven't)"
           div_
             [class_ "bg-bgBase p-3 rounded monospace text-sm overflow-x-auto border border-strokeWeak"]
-            "go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest"
-          p_ [class_ "text-xs text-textWeak mt-2 leading-relaxed"] "Requires Go 1.20 or later"
+            "curl monoscope.tech/install.sh | sh && monoscope auth login"
 
         -- Step 2: Run command
         div_ [class_ "p-4 bg-fillWeak rounded-lg"] do
@@ -691,9 +690,7 @@ integrationsPage pid apikey =
             pre_ [class_ "bg-bgBase p-3 rounded monospace text-sm overflow-x-auto border border-strokeWeak", id_ "telemetrygen-cmd"]
               $ code_
               $ toHtml
-              $ "telemetrygen traces --otlp-endpoint localhost:4317 \\\n  --otlp-insecure \\\n  --otlp-header 'Authorization=\"Bearer "
-              <> apikey
-              <> "\"' \\\n  --traces 10 \\\n  --duration 5s"
+              "monoscope telemetrygen --kind=trace --count=10"
             button_
               [ class_ "absolute top-2 right-2 px-3 py-1 text-xs bg-fillBrand-strong rounded text-textInverse-strong flex items-center gap-1 hover:bg-fillBrand-strong/90"
               , type_ "button"