Update HTTP Semantic Conventions to Stable Versions

api/hs-opentelemetry-api.cabal

@@ -1,6 +1,6 @@
 cabal-version: 1.12
 
--- This file has been generated from package.yaml by hpack version 0.35.2.
+-- This file has been generated from package.yaml by hpack version 0.36.0.
 --
 -- see: https://github.com/sol/hpack
 
@@ -52,6 +52,7 @@ library
       OpenTelemetry.Resource.Service
       OpenTelemetry.Resource.Telemetry
       OpenTelemetry.Resource.Webengine
+      OpenTelemetry.SemanticsConfig
       OpenTelemetry.Trace.Core
       OpenTelemetry.Trace.Id
       OpenTelemetry.Trace.Id.Generator
@@ -83,6 +84,7 @@ library
     , http-types
     , memory
     , mtl
+    , safe-exceptions
     , template-haskell
     , text
     , thread-utils-context ==0.3.*
@@ -99,6 +101,7 @@ test-suite hs-opentelemetry-api-test
   main-is: Spec.hs
   other-modules:
       OpenTelemetry.BaggageSpec
+      OpenTelemetry.SemanticsConfigSpec
       OpenTelemetry.Trace.SamplerSpec
       OpenTelemetry.Trace.TraceFlagsSpec
       Paths_hs_opentelemetry_api
@@ -124,6 +127,7 @@ test-suite hs-opentelemetry-api-test
     , http-types
     , memory
     , mtl
+    , safe-exceptions
     , template-haskell
     , text
     , thread-utils-context ==0.3.*

api/package.yaml

@@ -44,6 +44,7 @@ dependencies:
 - ghc-prim
 - unliftio-core
 - vector-builder
+- safe-exceptions
 
 library:
   source-dirs: src

api/src/OpenTelemetry/SemanticsConfig.hs

@@ -0,0 +1,90 @@
+{-# LANGUAGE OverloadedStrings #-}
+
+module OpenTelemetry.SemanticsConfig (
+  SemanticsOptions (httpOption),
+  HttpOption (..),
+  getSemanticsOptions,
+  getSemanticsOptions',
+) where
+
+import Control.Exception.Safe (throwIO, tryAny)
+import Data.IORef (newIORef, readIORef, writeIORef)
+import qualified Data.Text as T
+import System.Environment (lookupEnv)
+import System.IO.Unsafe (unsafePerformIO)
+
+
+{- | This is a record that contains options for whether the new stable semantics conventions should be emitted.
+Semantics conventions that have been declared stable:
+- [http](https://opentelemetry.io/blog/2023/http-conventions-declared-stable/#migration-plan)
+-}
+data SemanticsOptions = SemanticsOptions {httpOption :: HttpOption}
+
+
+-- | This option determines whether stable, old, or both kinds of http attributes are emitted.
+data HttpOption
+  = Stable
+  | StableAndOld
+  | Old
+  deriving (Show, Eq)
+
+
+-- | These are the default values emitted if OTEL_SEM_CONV_STABILITY_OPT_IN is unset or does not contain values for a specific category of option.
+defaultOptions :: SemanticsOptions
+defaultOptions = SemanticsOptions {httpOption = Old}
+
+
+-- | Detects the presence of "http/dup" or "http" in OTEL_SEMCONV_STABILITY_OPT_IN or uses the default option if they are not there.
+parseHttpOption :: (Foldable t) => t T.Text -> HttpOption
+parseHttpOption envs
+  | "http/dup" `elem` envs = StableAndOld
+  | "http" `elem` envs = Stable
+  | otherwise = httpOption defaultOptions
+
+
+-- | Detects the presence of semantics options in OTEL_SEMCONV_STABILITY_OPT_IN or uses the defaultOptions if they are not present.
+parseSemanticsOptions :: Maybe String -> SemanticsOptions
+parseSemanticsOptions Nothing = defaultOptions
+parseSemanticsOptions (Just env) = SemanticsOptions {..}
+  where
+    envs = fmap T.strip $ T.splitOn "," $ T.pack env
+    httpOption = parseHttpOption envs
+
+
+{- | Version of getSemanticsOptions that is not memoized. It is recommended to use getSemanticsOptions for efficiency purposes
+unless it is necessary to retrieve the value of OTEL_SEMCONV_STABILITY_OPT_IN every time getSemanticsOptions' is called.
+-}
+getSemanticsOptions' :: IO SemanticsOptions
+getSemanticsOptions' = parseSemanticsOptions <$> lookupEnv "OTEL_SEMCONV_STABILITY_OPT_IN"
+
+
+{- | Create a new memoized IO action using an 'IORef' under the surface. Note that
+the action may be run in multiple threads simultaneously, so this may not be
+thread safe (depending on the underlying action). For the sake of reading an environment
+variable and parsing some stuff, we don't have to be concerned about thread-safety.
+-}
+memoize :: IO a -> IO (IO a)
+memoize action = do
+  ref <- newIORef Nothing
+  pure $ do
+    mres <- readIORef ref
+    res <- case mres of
+      Just res -> pure res
+      Nothing -> do
+        res <- tryAny action
+        writeIORef ref $ Just res
+        pure res
+    either throwIO pure res
+
+
+{-  | Retrieves OTEL_SEMCONV_STABILITY_OPT_IN and parses it into SemanticsOptions.
+
+This uses the [global IORef trick](https://www.parsonsmatt.org/2021/04/21/global_ioref_in_template_haskell.html)
+to memoize the settings for efficiency. Note that getSemanticsOptions stores and returns the
+value of the first time it was called and will not change when OTEL_SEMCONV_STABILITY_OPT_IN
+is updated. Use getSemanticsOptions' to read OTEL_SEMCONV_STABILITY_OPT_IN every time the
+function is called.
+-}
+getSemanticsOptions :: IO SemanticsOptions
+getSemanticsOptions = unsafePerformIO $ memoize getSemanticsOptions'
+{-# NOINLINE getSemanticsOptions #-}

api/test/OpenTelemetry/SemanticsConfigSpec.hs

@@ -0,0 +1,44 @@
+module OpenTelemetry.SemanticsConfigSpec where
+
+import OpenTelemetry.SemanticsConfig
+import System.Environment
+import Test.Hspec
+
+
+envVarName :: String
+envVarName = "OTEL_SEMCONV_STABILITY_OPT_IN"
+
+
+spec :: Spec
+spec = do
+  describe "SemanticsConfig" $ do
+    describe "HttpOption" $ do
+      it "defaults to 'Old' when env var has no value" $ do
+        unsetEnv envVarName
+        semanticsOptions <- getSemanticsOptions'
+        httpOption semanticsOptions `shouldBe` Old
+      mapM_
+        ( \(envVarVal, expectedVal) ->
+            it ("returns " ++ show expectedVal ++ " when env var is " ++ show envVarVal) $ do
+              setEnv envVarName envVarVal
+              semanticsOptions <- getSemanticsOptions'
+              httpOption semanticsOptions `shouldBe` expectedVal
+        )
+        [ ("http", Stable)
+        , ("http/du", Old) -- intentionally similar to both "http/dup" and "http"
+        , ("http/dup", StableAndOld)
+        , ("http/dup,http", StableAndOld)
+        , ("http,http/dup", StableAndOld)
+        , ("http,something-random,http/dup", StableAndOld)
+        ]
+    context "memoization" $ do
+      it "works" $ do
+        setEnv envVarName "http"
+        semanticsOptions <- getSemanticsOptions
+        httpOption semanticsOptions `shouldBe` Stable
+      it ("does not change when " ++ envVarName ++ " changes") $ do
+        setEnv envVarName "http"
+        semanticsOptions <- getSemanticsOptions
+        setEnv envVarName "http/dup"
+        semanticsOptions <- getSemanticsOptions
+        httpOption semanticsOptions `shouldBe` Stable -- and not StableAndOld because of memoization

api/test/Spec.hs

@@ -13,6 +13,7 @@ import OpenTelemetry.Attributes (lookupAttribute)
 
 import qualified OpenTelemetry.BaggageSpec as Baggage
 import OpenTelemetry.Context
+import qualified OpenTelemetry.SemanticsConfigSpec as SemanticsConfigSpec
 import OpenTelemetry.Trace.Core
 import qualified OpenTelemetry.Trace.SamplerSpec as Sampler
 import qualified OpenTelemetry.Trace.TraceFlagsSpec as TraceFlags
@@ -54,3 +55,4 @@ main = hspec $ do
   Baggage.spec
   Sampler.spec
   TraceFlags.spec
+  SemanticsConfigSpec.spec

hie.yaml

@@ -6,6 +6,12 @@ cradle:
     - path: "api/test"
       component: "hs-opentelemetry-api:test:hs-opentelemetry-api-test"
 
+    - path: "examples/hspec/src"
+      component: "hspec-example:lib"
+
+    - path: "examples/hspec/test"
+      component: "hspec-example:test:test"
+
     - path: "examples/yesod-minimal/src"
       component: "yesod-minimal:lib"
 
@@ -90,8 +96,8 @@ cradle:
     - path: "propagators/b3/src"
       component: "hs-opentelemetry-propagator-b3:lib"
 
-    - path: "propagators/b3/test/spec"
-      component: "hs-opentelemetry-propagator-b3:test:spec"
+    - path: "propagators/b3/test"
+      component: "hs-opentelemetry-propagator-b3:test:hs-opentelemetry-propagator-b3-test"
 
     - path: "propagators/datadog/src"
       component: "hs-opentelemetry-propagator-datadog:lib"
@@ -105,6 +111,21 @@ cradle:
     - path: "propagators/datadog/benchmark/header-codec/main.hs"
       component: "hs-opentelemetry-propagator-datadog:bench:header-codec"
 
+    - path: "propagators/datadog/old-src/main.hs"
+      component: "hs-opentelemetry-propagator-datadog:bench:header-codec"
+
+    - path: "propagators/datadog/benchmark/header-codec/Raw.hs"
+      component: "hs-opentelemetry-propagator-datadog:bench:header-codec"
+
+    - path: "propagators/datadog/benchmark/header-codec/String.hs"
+      component: "hs-opentelemetry-propagator-datadog:bench:header-codec"
+
+    - path: "propagators/datadog/old-src/Raw.hs"
+      component: "hs-opentelemetry-propagator-datadog:bench:header-codec"
+
+    - path: "propagators/datadog/old-src/String.hs"
+      component: "hs-opentelemetry-propagator-datadog:bench:header-codec"
+
     - path: "propagators/w3c/src"
       component: "hs-opentelemetry-propagator-w3c:lib"
 
@@ -116,9 +137,3 @@ cradle:
 
     - path: "sdk/test"
       component: "hs-opentelemetry-sdk:test:hs-opentelemetry-sdk-test"
-
-    - path: "utils/exceptions/src"
-      component: "hs-opentelemetry-utils-exceptions:lib"
-
-    - path: "utils/exceptions/test"
-      component: "hs-opentelemetry-utils-exceptions:test:exceptions-test"

instrumentation/http-client/hs-opentelemetry-instrumentation-http-client.cabal

@@ -1,6 +1,6 @@
 cabal-version: 1.12
 
--- This file has been generated from package.yaml by hpack version 0.35.2.
+-- This file has been generated from package.yaml by hpack version 0.36.0.
 --
 -- see: https://github.com/sol/hpack
 

instrumentation/http-client/src/OpenTelemetry/Instrumentation/HttpClient.hs

@@ -6,6 +6,11 @@
 - Use internals to instrument a particular callsite using modifyRequest, modifyResponse (Next best)
 - Provide a middleware to pull from the thread-local state (okay)
 - Modify the global manager to pull from the thread-local state (least good, can't be helped sometimes)
+
+[New HTTP semantic conventions have been declared stable.](https://opentelemetry.io/blog/2023/http-conventions-declared-stable/#migration-plan) Opt-in by setting the environment variable OTEL_SEMCONV_STABILITY_OPT_IN to
+- "http" - to use the stable conventions
+- "http/dup" - to emit both the old and the stable conventions
+Otherwise, the old conventions will be used. The stable conventions will replace the old conventions in the next major release of this library.
 -}
 module OpenTelemetry.Instrumentation.HttpClient (
   withResponse,
@@ -68,8 +73,8 @@ withResponse
   -> (Client.Response Client.BodyReader -> m a)
   -> m a
 withResponse httpConf req man f = do
-  t <- httpTracerProvider
-  inSpan'' t "withResponse" (addAttributesToSpanArguments callerAttributes spanArgs) $ \_wrSpan -> do
+  tracer <- httpTracerProvider
+  inSpan'' tracer "withResponse" (addAttributesToSpanArguments callerAttributes spanArgs) $ \_wrSpan -> do
     ctxt <- getContext
     -- TODO would like to capture the req/resp time specifically
     -- inSpan "http.request" (defaultSpanArguments { startingKind = Client }) $ \httpReqSpan -> do
@@ -88,8 +93,8 @@ withResponse httpConf req man f = do
 -}
 httpLbs :: (MonadUnliftIO m, HasCallStack) => HttpClientInstrumentationConfig -> Client.Request -> Client.Manager -> m (Client.Response L.ByteString)
 httpLbs httpConf req man = do
-  t <- httpTracerProvider
-  inSpan'' t "httpLbs" (addAttributesToSpanArguments callerAttributes spanArgs) $ \_ -> do
+  tracer <- httpTracerProvider
+  inSpan'' tracer "httpLbs" (addAttributesToSpanArguments callerAttributes spanArgs) $ \_ -> do
     ctxt <- getContext
     req' <- instrumentRequest httpConf ctxt req
     resp <- liftIO $ Client.httpLbs req' man
@@ -102,8 +107,8 @@ httpLbs httpConf req man = do
 -}
 httpNoBody :: (MonadUnliftIO m, HasCallStack) => HttpClientInstrumentationConfig -> Client.Request -> Client.Manager -> m (Client.Response ())
 httpNoBody httpConf req man = do
-  t <- httpTracerProvider
-  inSpan'' t "httpNoBody" (addAttributesToSpanArguments callerAttributes spanArgs) $ \_ -> do
+  tracer <- httpTracerProvider
+  inSpan'' tracer "httpNoBody" (addAttributesToSpanArguments callerAttributes spanArgs) $ \_ -> do
     ctxt <- getContext
     req' <- instrumentRequest httpConf ctxt req
     resp <- liftIO $ Client.httpNoBody req' man
@@ -141,8 +146,8 @@ httpNoBody httpConf req man = do
 -}
 responseOpen :: (MonadUnliftIO m, HasCallStack) => HttpClientInstrumentationConfig -> Client.Request -> Client.Manager -> m (Client.Response Client.BodyReader)
 responseOpen httpConf req man = do
-  t <- httpTracerProvider
-  inSpan'' t "responseOpen" (addAttributesToSpanArguments callerAttributes spanArgs) $ \_ -> do
+  tracer <- httpTracerProvider
+  inSpan'' tracer "responseOpen" (addAttributesToSpanArguments callerAttributes spanArgs) $ \_ -> do
     ctxt <- getContext
     req' <- instrumentRequest httpConf ctxt req
     resp <- liftIO $ Client.responseOpen req' man