Merge pull request #73 from ivantopo/keep-assigned-http-operation-name

keep any operation name assigned by the HTTP Server instrumentation

Author: ivantopo

build.sbt

@@ -18,11 +18,11 @@ resolvers += Resolver.mavenLocal
 resolvers += Resolver.bintrayRepo("hseeberger", "maven")
 
 
-val kamonCore           = "io.kamon" %% "kamon-core"                    % "2.0.0"
-val kamonTestKit        = "io.kamon" %% "kamon-testkit"                 % "2.0.0"
-val kamonCommon         = "io.kamon" %% "kamon-instrumentation-common"  % "2.0.0"
-val kamonAkka25         = "io.kamon" %% "kamon-akka"                    % "2.0.0"
-val kanelaAgent         = "io.kamon" %  "kanela-agent"                  % "1.0.1"
+val kamonCore           = "io.kamon" %% "kamon-core"                    % "2.0.3"
+val kamonTestKit        = "io.kamon" %% "kamon-testkit"                 % "2.0.3"
+val kamonCommon         = "io.kamon" %% "kamon-instrumentation-common"  % "2.0.1"
+val kamonAkka25         = "io.kamon" %% "kamon-akka"                    % "2.0.1"
+val kanelaAgent         = "io.kamon" %  "kanela-agent"                  % "1.0.4"
 
 val akkaHttpJson        = "de.heikoseeberger" %% "akka-http-json4s"     % "1.27.0"
 val json4sNative        = "org.json4s"        %% "json4s-native"        % "3.6.7"

kamon-akka-http/src/main/scala-2.11/kamon/instrumentation/akka/http/AkkaHttpServerInstrumentation.scala

@@ -179,17 +179,25 @@ object ResolveOperationNameOnRouteInterceptor {
     // by accessing the Span and changing it directly there, so we wouldn't want to overwrite that.
 
     Kamon.currentContext().get(LastAutomaticOperationNameEdit.Key).foreach(lastEdit => {
-      if(Kamon.currentSpan().operationName() == lastEdit.operationName) {
+      val currentSpan = Kamon.currentSpan()
+
+      if(lastEdit.allowAutomaticChanges) {
+        if(currentSpan.operationName() == lastEdit.operationName) {
         val allMatches = requestContext.asInstanceOf[HasMatchingContext].matchingContext.reverse.map(singleMatch)
         val operationName = allMatches.mkString("")
 
         if(operationName.nonEmpty) {
-          Kamon.currentSpan()
+            currentSpan
             .name(operationName)
             .takeSamplingDecision()
 
           lastEdit.operationName = operationName
         }
+        } else {
+          lastEdit.allowAutomaticChanges = false
+        }
+      } else {
+        currentSpan.takeSamplingDecision()
       }
     })
 
@@ -220,13 +228,27 @@ object ResolveOperationNameOnRouteInterceptor {
   }
 }
 
-class LastAutomaticOperationNameEdit(@volatile var operationName: String)
+/**
+  * Tracks the last operation name that was automatically assigned to an operation via instrumentation. The
+  * instrumentation might assign a name to the operations via settings on the HTTP Server instrumentation instance or
+  * via the Path directives instrumentation, but might never reassign a name if the user somehow assigned their own name
+  * to the operation. Users chan change operation names by:
+  *   - Using operation mappings via configuration of the HTTP Server.
+  *   - Providing a custom HTTP Operation Name Generator for the server.
+  *   - Using the "operationName" directive.
+  *   - Directly accessing the Span for the current operation and changing the name on it.
+  *
+  */
+class LastAutomaticOperationNameEdit(
+  @volatile var operationName: String,
+  @volatile var allowAutomaticChanges: Boolean
+)
 
 object LastAutomaticOperationNameEdit {
   val Key = Context.key[Option[LastAutomaticOperationNameEdit]]("laone", None)
 
-  def apply(operationName: String): LastAutomaticOperationNameEdit =
-    new LastAutomaticOperationNameEdit(operationName)
+  def apply(operationName: String, allowAutomaticChanges: Boolean): LastAutomaticOperationNameEdit =
+    new LastAutomaticOperationNameEdit(operationName, allowAutomaticChanges)
 }
 
 object RequestContextCopyInterceptor {

kamon-akka-http/src/main/scala-2.12/kamon/instrumentation/akka/http/AkkaHttpServerInstrumentation.scala

@@ -179,17 +179,25 @@ object ResolveOperationNameOnRouteInterceptor {
     // by accessing the Span and changing it directly there, so we wouldn't want to overwrite that.
 
     Kamon.currentContext().get(LastAutomaticOperationNameEdit.Key).foreach(lastEdit => {
-      if(Kamon.currentSpan().operationName() == lastEdit.operationName) {
+      val currentSpan = Kamon.currentSpan()
+
+      if(lastEdit.allowAutomaticChanges) {
+        if(currentSpan.operationName() == lastEdit.operationName) {
         val allMatches = requestContext.asInstanceOf[HasMatchingContext].matchingContext.reverse.map(singleMatch)
         val operationName = allMatches.mkString("")
 
         if(operationName.nonEmpty) {
-          Kamon.currentSpan()
+            currentSpan
             .name(operationName)
             .takeSamplingDecision()
 
           lastEdit.operationName = operationName
         }
+        } else {
+          lastEdit.allowAutomaticChanges = false
+        }
+      } else {
+        currentSpan.takeSamplingDecision()
       }
     })
 
@@ -220,13 +228,27 @@ object ResolveOperationNameOnRouteInterceptor {
   }
 }
 
-class LastAutomaticOperationNameEdit(@volatile var operationName: String)
+/**
+  * Tracks the last operation name that was automatically assigned to an operation via instrumentation. The
+  * instrumentation might assign a name to the operations via settings on the HTTP Server instrumentation instance or
+  * via the Path directives instrumentation, but might never reassign a name if the user somehow assigned their own name
+  * to the operation. Users chan change operation names by:
+  *   - Using operation mappings via configuration of the HTTP Server.
+  *   - Providing a custom HTTP Operation Name Generator for the server.
+  *   - Using the "operationName" directive.
+  *   - Directly accessing the Span for the current operation and changing the name on it.
+  *
+  */
+class LastAutomaticOperationNameEdit(
+  @volatile var operationName: String,
+  @volatile var allowAutomaticChanges: Boolean
+)
 
 object LastAutomaticOperationNameEdit {
   val Key = Context.key[Option[LastAutomaticOperationNameEdit]]("laone", None)
 
-  def apply(operationName: String): LastAutomaticOperationNameEdit =
-    new LastAutomaticOperationNameEdit(operationName)
+  def apply(operationName: String, allowAutomaticChanges: Boolean): LastAutomaticOperationNameEdit =
+    new LastAutomaticOperationNameEdit(operationName, allowAutomaticChanges)
 }
 
 object RequestContextCopyInterceptor {

kamon-akka-http/src/main/scala-2.13/kamon/instrumentation/akka/http/AkkaHttpServerInstrumentation.scala

@@ -179,17 +179,25 @@ object ResolveOperationNameOnRouteInterceptor {
     // by accessing the Span and changing it directly there, so we wouldn't want to overwrite that.
 
     Kamon.currentContext().get(LastAutomaticOperationNameEdit.Key).foreach(lastEdit => {
-      if(Kamon.currentSpan().operationName() == lastEdit.operationName) {
-        val allMatches = requestContext.asInstanceOf[HasMatchingContext].matchingContext.reverse.map(singleMatch)
-        val operationName = allMatches.mkString("")
+      val currentSpan = Kamon.currentSpan()
 
-        if(operationName.nonEmpty) {
-          Kamon.currentSpan()
-            .name(operationName)
-            .takeSamplingDecision()
+      if(lastEdit.allowAutomaticChanges) {
+        if(currentSpan.operationName() == lastEdit.operationName) {
+          val allMatches = requestContext.asInstanceOf[HasMatchingContext].matchingContext.reverse.map(singleMatch)
+          val operationName = allMatches.mkString("")
 
-          lastEdit.operationName = operationName
+          if (operationName.nonEmpty) {
+            currentSpan
+              .name(operationName)
+              .takeSamplingDecision()
+
+            lastEdit.operationName = operationName
+          }
+        } else {
+          lastEdit.allowAutomaticChanges = false
         }
+      } else {
+        currentSpan.takeSamplingDecision()
       }
     })
 
@@ -220,13 +228,27 @@ object ResolveOperationNameOnRouteInterceptor {
   }
 }
 
-class LastAutomaticOperationNameEdit(@volatile var operationName: String)
+/**
+  * Tracks the last operation name that was automatically assigned to an operation via instrumentation. The
+  * instrumentation might assign a name to the operations via settings on the HTTP Server instrumentation instance or
+  * via the Path directives instrumentation, but might never reassign a name if the user somehow assigned their own name
+  * to the operation. Users chan change operation names by:
+  *   - Using operation mappings via configuration of the HTTP Server.
+  *   - Providing a custom HTTP Operation Name Generator for the server.
+  *   - Using the "operationName" directive.
+  *   - Directly accessing the Span for the current operation and changing the name on it.
+  *
+  */
+class LastAutomaticOperationNameEdit(
+  @volatile var operationName: String,
+  @volatile var allowAutomaticChanges: Boolean
+)
 
 object LastAutomaticOperationNameEdit {
   val Key = Context.key[Option[LastAutomaticOperationNameEdit]]("laone", None)
 
-  def apply(operationName: String): LastAutomaticOperationNameEdit =
-    new LastAutomaticOperationNameEdit(operationName)
+  def apply(operationName: String, allowAutomaticChanges: Boolean): LastAutomaticOperationNameEdit =
+    new LastAutomaticOperationNameEdit(operationName, allowAutomaticChanges)
 }
 
 object RequestContextCopyInterceptor {

kamon-akka-http/src/main/scala/kamon/instrumentation/akka/http/ServerFlowWrapper.scala

@@ -65,12 +65,20 @@ object ServerFlowWrapper {
           val requestHandler = httpServerInstrumentation.createHandler(toRequest(request), deferSamplingDecision = true)
             .requestReceived()
 
+          val defaultOperationName = httpServerInstrumentation.settings.defaultOperationName
+          val requestSpan = requestHandler.span
+
+          // Automatic Operation name changes will only be allowed if the initial name HTTP Server didn't assign a
+          // user-defined name to the operation (that would be, either via an Operation Name Generator or a custom
+          // operation mapping).
+          val allowAutomaticChanges = requestSpan.operationName() == defaultOperationName
+
           _pendingRequests.enqueue(requestHandler)
 
           // The only reason why it's safe to leave the Thread dirty is because the Actor
           // instrumentation will cleanup afterwards.
           Kamon.storeContext(requestHandler.context.withEntry(
-            LastAutomaticOperationNameEdit.Key, Option(LastAutomaticOperationNameEdit(requestHandler.span.operationName()))
+            LastAutomaticOperationNameEdit.Key, Option(LastAutomaticOperationNameEdit(requestSpan.operationName(), allowAutomaticChanges))
           ))
 
           push(requestOut, request)

kamon-akka-http/src/test/resources/application.conf

@@ -2,4 +2,150 @@ kamon {
   trace.sampler = "always"
 }
 
-akka.http.server.preview.enable-http2 = on
+akka.http.server.preview.enable-http2 = on
+
+
+
+kamon.instrumentation.akka.http {
+
+  # Settings to control the HTTP Server instrumentation.
+  #
+  # IMPORTANT: Besides the "initial-operation-name" and "unhandled-operation-name" settings, the entire configuration of
+  # the HTTP Server Instrumentation is based on the constructs provided by the Kamon Instrumentation Common library
+  # which will always fallback to the settings found under the "kamon.instrumentation.http-server.default" path. The
+  # default settings have been included here to make them easy to find and understand in the context of this project and
+  # commented out so that any changes to the default settings will actually have effect.
+  #
+  server {
+
+    #
+    # Configuration for HTTP context propagation.
+    #
+    propagation {
+
+      # Enables or disables HTTP context propagation on this HTTP server instrumentation. Please note that if
+      # propagation is disabled then some distributed tracing features will not be work as expected (e.g. Spans can
+      # be created and reported but will not be linked across boundaries nor take trace identifiers from tags).
+      #enabled = yes
+
+      # HTTP propagation channel to b used by this instrumentation. Take a look at the kamon.propagation.http.default
+      # configuration for more details on how to configure the detault HTTP context propagation.
+      #channel = "default"
+    }
+
+
+    #
+    # Configuration for HTTP server metrics collection.
+    #
+    metrics {
+
+      # Enables collection of HTTP server metrics. When enabled the following metrics will be collected, assuming
+      # that the instrumentation is fully compliant:
+      #
+      #   - http.server.requets
+      #   - http.server.request.active
+      #   - http.server.request.size
+      #   - http.server.response.size
+      #   - http.server.connection.lifetime
+      #   - http.server.connection.usage
+      #   - http.server.connection.open
+      #
+      # All metrics have at least three tags: component, interface and port. Additionally, the http.server.requests
+      # metric will also have a status_code tag with the status code group (1xx, 2xx and so on).
+      #
+      #enabled = yes
+    }
+
+
+    #
+    # Configuration for HTTP request tracing.
+    #
+    tracing {
+
+      # Enables HTTP request tracing. When enabled the instrumentation will create Spans for incoming requests
+      # and finish them when the response is sent back to the clients.
+      #enabled = yes
+
+      # Select a context tag that provides a preferred trace identifier. The preferred trace identifier will be used
+      # only if all these conditions are met:
+      #   - the context tag is present.
+      #   - there is no parent Span on the incoming context (i.e. this is the first service on the trace).
+      #   - the identifier is valid in accordance to the identity provider.
+      #preferred-trace-id-tag = "none"
+
+      # Enables collection of span metrics using the `span.processing-time` metric.
+      #span-metrics = on
+
+      # Select which tags should be included as span and span metric tags. The possible options are:
+      #   - span: the tag is added as a Span tag (i.e. using span.tag(...))
+      #   - metric: the tag is added a a Span metric tag (i.e. using span.tagMetric(...))
+      #   - off: the tag is not used.
+      #
+      tags {
+
+        # Use the http.url tag.
+        #url = span
+
+        # Use the http.method tag.
+        #method = metric
+
+        # Use the http.status_code tag.
+        #status-code = metric
+
+        # Copy tags from the context into the Spans with the specified purpouse. For example, to copy a customer_type
+        # tag from the context into the HTTP Server Span created by the instrumentation, the following configuration
+        # should be added:
+        #
+        # from-context {
+        #   customer_type = span
+        # }
+        #
+        from-context {
+
+        }
+      }
+
+      # Controls writing trace and span identifiers to HTTP response headers sent by the instrumented servers. The
+      # configuration can be set to either "none" to disable writing the identifiers on the response headers or to
+      # the header name to be used when writing the identifiers.
+      response-headers {
+
+        # HTTP response header name for the trace identifier, or "none" to disable it.
+        #trace-id = "trace-id"
+
+        # HTTP response header name for the server span identifier, or "none" to disable it.
+        #span-id = none
+      }
+
+      # Custom mappings between routes and operation names.
+      operations {
+
+        # The default operation name to be used when creating Spans to handle the HTTP server requests. In most
+        # cases it is not possible to define an operation name right at the moment of starting the HTTP server Span
+        # and in those cases, this operation name will be initially assigned to the Span. Instrumentation authors
+        # should do their best effort to provide a suitable operation name or make use of the "mappings" facilities.
+        #default = "http.server.request"
+
+        # Provides custom mappings from HTTP paths into operation names. Meant to be used in cases where the bytecode
+        # instrumentation is not able to provide a sensible operation name that is free of high cardinality values.
+        # For example, with the following configuration:
+        #   mappings {
+        #     "/organization/*/user/*/profile" = "/organization/:orgID/user/:userID/profile"
+        #     "/events/*/rsvps" = "EventRSVPs"
+        #   }
+        #
+        # Requests to "/organization/3651/user/39652/profile" and "/organization/22234/user/54543/profile" will have
+        # the same operation name "/organization/:orgID/user/:userID/profile".
+        #
+        # Similarly, requests to "/events/aaa-bb-ccc/rsvps" and "/events/1234/rsvps" will have the same operation
+        # name "EventRSVPs".
+        #
+        # The patterns are expressed as globs and the operation names are free form.
+        #
+        mappings {
+          "/name-will-be-changed" = "named-via-config"
+        }
+      }
+    }
+  }
+}