path: root/kamon-core/src/main/resources/reference.conf

kamon {

  environment {

    # Identifier for this service.
    service = "kamon-application"

    # Identifier for the host where this service is running. If set to `auto` Kamon will resolve the hostname using
    # the resolved name for localhost.
    host = "auto"

    # Identifier for a particular instance of this service. If set to `auto` Kamon will use the pattern service@host.
    instance = "auto"

    # Arbitrary key-value pairs that further identify the environment where this service instance is running. Typically
    # these tags will be used by the reporting modules as additional tags for all metrics or spans. Take a look at each
    # reporter module's configuration to ensure these tags are supported and included in the reported data. Example:
    #
    # kamon.environment.tags {
    #   env = "staging"
    #   region = "us-east-1"
    # }
    tags {

    }
  }

  status {

    # When enabled, Kamon will start an embedded web server to publish the status mini-site that contains basic
    # status and debugging information.
    enabled = true

    # Controls the hostname and port in which the status mini-site HTTP server will be listening.
    listen {
      hostname = "0.0.0.0"
      port = 9912
    }
  }

  # Modules that can be automatically discovered and started by Kamon. The configuration for each module has the
  # following schema:
  #
  # kamon.modules {
  #   module-name {
  #     enabled = true
  #     class = "com.example.ModuleClass"
  #   }
  # }
  #
  # All available modules in the classpath are started when calling Kamon.loadModules() and stopped when calling
  # Kamon.stopModules().
  #
  modules {

  }

  # Pool size for the executor service that will run sampling on RangeSampler instruments. This scheduler is accesible
  # through Kamon.scheduler()
  scheduler-pool-size = 2


  metric {

    # Interval at which metric snapshots will be collected and sent to all metric reporters.
    tick-interval = 60 seconds

    # When optimistic tick alignment is enabled the metrics ticker will try to schedule the ticks to happen as close as
    # possible to round tick-interval units. E.g. if the tick-interval is set to 60 seconds then Kamon will try to
    # schedule the ticks at the beginning of each minute; if the tick-interval is set to 20 seconds then Kamon will try
    # to schedule the ticks at 0, 20, and 40 seconds of each minute. The alignment is not meant to be perfect, just to
    # improve the ability to correlate the timestamp reported in ticks with logs.
    optimistic-tick-alignment = yes

    # Thread pool size used by the metrics refresh scheduler. This pool is only used to periodically sampling
    # range-sampler values.
    refresh-scheduler-pool-size = 2

    instrument-factory {

      # Default instrument settings for histograms and min max counters. The actual settings to be used when creating
      # instruments is determined by merging the default settings, code settings and custom-settings using the following
      # priorities (top wins):
      #
      #   - any setting in the `custom-settings` section for the given category/instrument.
      #   - code settings provided when creating the instrument.
      #   - `default-settings` bellow.
      #
      default-settings {
        histogram {
          lowest-discernible-value = 1
          highest-trackable-value = 3600000000000
          significant-value-digits = 2
        }

        range-sampler {
          lowest-discernible-value = 1
          highest-trackable-value = 3600000000000
          significant-value-digits = 2
          sample-interval = 200 ms
        }
      }

      # Custom settings for instruments of a given metric. The settings provided in this section override the default
      # and manually provided settings when creating metrics. All settings are optional in this section and default
      # values from the `kamon.metric.instrument-factory.default-settings` will be used in case of any setting being
      # missing.
      #
      # Example:
      # If you wish to change the highest trackable value setting of the `span.elapsed-time` metric, you should include
      # the following configuration in your application.conf file:
      #
      #   kamon.metric.instrument-factory.custom-settings {
      #     "span.elapsed-time" {
      #       highest-trackable-value = 5000
      #     }
      #   }
      #
      custom-settings {

      }
    }
  }


  trace {

    # Interval at which sampled finished spans will be flushed to SpanReporters.
    tick-interval = 10 seconds

    # Size of the internal queue where sampled spans will stay until they get flushed. If the queue becomes full then
    # sampled finished spans will be dropped in order to avoid consuming excessive amounts of memory. Each configured
    # reporter has a separate queue.
    reporter-queue-size = 4096


    # Decide whether a new, locally created Span should have the same Span Identifier as it's remote parent (if any) or
    # get a new local identifier. Certain tracing systems use the same Span Identifier to represent both sides (client
    # and server) of a RPC call, if you are reporting data to such systems then this option should be enabled.
    #
    # If you are using Zipkin, keep this option enabled. If you are using Jaeger, disable it.
    join-remote-parents-with-same-span-id = no

    # Configures a sample that decides which traces should be reported to the trace backends. The possible values are:
    #   - always: report all traces.
    #   - never:  don't report any trace.
    #   - random: randomly decide using the probability defined in the random-sampler.probability setting.
    #
    sampler = "random"

    # The random sampler uses the "chance" setting and a random number to take a decision, if the random number is
    # on the upper (chance * 100) percent of the number spectrum the trace will be sampled. E.g. a chance of 0.01 will
    # hint that 1% of all traces should be reported.
    random-sampler {

      # Probability of a span being sampled. Must be a value between 0 and 1.
      probability = 0.01
    }

    # The IdentityProvider used to generate Trace and Span Identifiers in Kamon. There are two default implementations
    # that ship with Kamon:
    #   - kamon.trace.IdentityProvider$Default: Creates 8-byte identifiers for both Traces and Spans.
    #   - kamon.trace.IdentityProvider$DoubleSizeTraceID: Creates 16-byte identifiers for Traces and 8-byte identifiers
    #     for Spans.
    #
    # Any external implementation can be configured here, as long as it can be instantiated with a parameterless constructor.
    identity-provider = "kamon.trace.IdentityProvider$Default"

    span-metrics {

      # When this option is enabled the metrics collected for Spans will automatically add a tag named "parentOperation"
      # with the name of the operation on the parent Span, if any.
      scope-spans-to-parent = yes
    }
  }

  propagation {

    http {

      # Default HTTP propagation. Unless specified otherwise, all instrumentation will use the configuration on
      # this section for HTTP context propagation.
      #
      default {

        # Configures how context tags will be propagated over HTTP headers.
        #
        tags {

          # Header name used to encode context tags.
          header-name = "context-tags"


          # Provide explicit mappins between context tags and the HTTP headers that will carry them. When there is
          # an explicit mapping for a tag, it will not be included in the default context header. For example, if
          # you wanted to use the an HTTP header called `X-Correlation-ID` for a context tag with key `correlationID`
          # you would need to include a the following configuration:
          #
          #   mappings {
          #     correlationID = "X-Correlation-ID"
          #   }
          #
          # The correlationID tag would always be read and written from the `X-Correlation-ID` header. The context
          # tag name is represented as the configuration key and the desired header name is represented by the
          # cofiguration value.
          #
          mappings {

          }
        }

        # Configure which entries should be read from incoming HTTP requests and writen to outgoing HTTP requests.
        #
        entries {

          # Specify mappings between Context keys and the Propagation.EntryReader[HeaderReader] implementation in charge
          # of reading them from the incoming HTTP request into the Context.
          incoming {

            # kamon.trace.SpanPropagation$B3 for default header format or kamon.trace.SpanPropagation$B3Simple for 'b3 single' header format.
            span = "kamon.trace.SpanPropagation$B3"
          }

          # Specify mappings betwen Context keys and the Propagation.EntryWriter[HeaderWriter] implementation in charge
          # of writing them to outgoing HTTP requests.
          outgoing {

            # kamon.trace.SpanPropagation$B3 for default header format or kamon.trace.SpanPropagation$B3Simple for 'b3 single' header format.
            span = "kamon.trace.SpanPropagation$B3"
          }
        }
      }
    }

    binary {

      # Default binaey propagation. Unless specified otherwise, all instrumentation will use the configuration on
      # this section for binary context propagation.
      #
      default {

        # Maximum outgoing Context size for binary transports. Contexts that surpass this limit will not be written to
        # the outgoing medium.
        max-outgoing-size = 2048

        # Configure which entries should be read from incoming messages and writen to outgoing messages.
        #
        entries {

          # Specify mappings between Context keys and the Propagation.EntryReader[ByteStreamReader] implementation in
          # charge of reading them from the incoming messages into the Context.
          incoming {
            span = "kamon.trace.SpanPropagation$Colfer"
          }

          # Specify mappings betwen Context keys and the Propagation.EntryWriter[ByteStreamWriter] implementation in
          # charge of writing them on the outgoing messages.
          outgoing {
            span = "kamon.trace.SpanPropagation$Colfer"
          }
        }
      }
    }
  }

  instrumentation {
    http-server {
      default {

        #
        # 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 {

            # Operation name for Spans created on requests that could not be handled by any route in the current
            # application.
            unhandled = "unhandled"

            # 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 {

            }
          }
        }
      }
    }
  }


  util {
    filters {

    }
  }
}