Configuration-based .NET Full Framework Trace SDK

The configuration-based .NET Full Framework Trace SDK enables a declarative specification of spans, and tags they should carry, and creating them by executing certain methods of your application.
The declarative approach is a little more expressive than the usage of the code-based Tracing SDK, although not offering all the capabilities. Before you implement custom tracing, read the tracing best practices.

Disclaimer

The configuration-based SDK is brittle against changes in your application. You may rename a class or a method, and all of a sudden the configuration does no longer match, and you lose your tracing data. Whenever possible, we advise to use the .NET Full Framework SDK, which is far more resilient against code changes and has more features to help you accomplish your goals.

Configuration

The configuration is specified in the configuration.yaml file.

Changes to the configuration of the configuration-based .NET Full Framework Trace SDK are automatically picked up by the Instana agent. Already instrumented applications need to be restarted to use the changed configuration.

The configuration based .NET Full Framework Trace SDK is available in the CLR Sensor version 1.1.44 or above. With versions prior to 1.1.47 it is an opt-in feature. To enable it, set the environment-variable INSTANA_CLR_SDKCONFIG to 1 in order to enable it. Version >= 1.1.47 do not need this switch anymore.

Format

The following listing describes the general format of the configuration:

# .NET Full Framework Tracing
com.instana.plugin.clr:
  instrumentation:
    sdk:
      targets:
        - match:
            type: class
            class: '<type-name>'
            method: '<method-name>'
            arguments: <number of arguments>
          span:
            name: '<span-name>'
            type: 'ENTRY' | 'EXIT' | 'INTERMEDIATE'
            tags:
              - name: '<name of tag>'
                kind: argument
                index: <0-based index of the method's argument>
              - name: '<name of tag>'
                kind: constant
                index: '<constant value>'
              - name: '<name of tag>'
                kind: return

Multiple targets can be defined within the targets key, each of which specifies one span to be created.
The match object of one target specifies the method to apply the instrumentation to.
The span object specifies how to build the span, including its name (which is used for example in Unbounded Analytics for the call.name filter) and which tags should be set.

Matching methods to instrument

The configuration-based SDK currently only supports matching of methods on classes. Instrumentation based on interfaces or base-classes (traversing the inheritance-path) are not supported yet.

This object describes the code point at which an instrumentation should take place:

  • type: Type of the code to instrument; supported values:
    • class, match a concrete class
  • name: Fully qualified name of the class, interface or base class to match
    For nested classes, the notation a.b.c.OutsideClass$NestedClass is expected
  • method: Name of the method of the given class, interface or base class of which an invocation should be recorded
  • arguments: Number of arguments the method takes (only overloads with this number of arguments will be matched). 0 if no arguments are passed in.

Specifying how the spans will look like

This object describes properties of the span that will be created if the method described in match is invoked:

  • name: Span name
  • type: Span type (optional); supported values:
    • ENTRY, used to indicate "incoming" calls from external systems
    • INTERMEDIATE, used to capture internal calls to "interesting" methods (default)
    • EXIT, used to indicate "outgoing" calls to external systems
  • tags: List of tags/annotations to capture and how to obtain their values (optional); supported values:
    • constant, capture a constant value
      • kind: constant
      • name: Name of the tag to create
      • value: Constant value of the tag to create
    • return, capture the return value of the method invocation
      • kind: return
      • name: Name of the tag to create; value will be the value of the returned object
    • argument, capture a specific argument value of the method invocation
      • kind: argument
      • name: Name of the tag to create
      • index: 0-based index of the argument to capture as value of the tag

If the captured value is null or Nullable<T> without value, the defined tag will not be added. Spans with missing tags can be looked up in Unbounded Analytics using the is not present operator in conjunction with the call.tag filter.

Erroneous Spans

If an Exception propagates outside of an instrumented method, the span will be automatically marked as errorneous, and the value of Exception::Message will be set as the error message, which you can search in Unbounded Analytics via the call.error.message tag.

Example

The following snippet shows an example configuration of how an application handling batch jobs could be traced:

com.instana.plugin.clr:
  instrumentation:
    sdk:
      targets:
        - match:
            type: class
            class: Example.BatchJobStarter
            method: ExecuteJob
            arguments: 1
          span:
            name: BatchJob
            type: ENTRY
            tags:
              - name: endpoint
                kind: constant
                value: BatchJob
              - name: batch.job
                kind: argument
                index: 0
        - match:
            type: class
            class: Example.ProprietaryDatabaseClient
            method: ExecuteQuery
            arguments: 1
          span:
            name: DatabaseCall
            type: EXIT
            tags:
              - name: db.connection_string
                kind: constant
                value: 'Data Source=SomeServer;Initial Catalog=SomeDB' 
              - name: db.statement
                kind: argument
                index: 0

First the method ExecuteJob in class Example.BatchJobStarter is instrumented to create entry spans with name BatchJob, the annotation endpoint with the constant value BatchJob, and the annotation batch.job with the first argument as its value.

Furthermore, outgoing DB calls during the batch processing, that is invocations of method ExecuteQuery in Example.ProprietaryDatabaseClient, will create exit spans with name DatabaseCall and the annotation db.connection_string with the constant value Data Source=SomeServer;Initial Catalog=SomeDB and annotation db.statement with the first argument of the method invocation.

Processing a new batch with ExecuteJob will start a new trace and subsequent DB updates with ExecuteQuery will be listed as child spans within it. All Instana features, like Unbounded Analytics, can be used identically to traces created with Instana AutoTrace.

Limitations

The following restrictions apply to the configuration-based .NET Full Framework Trace SDK:

  • Instrumenting constructors is not supported.
  • Starting a span in one method and closing it in another is not supported; that is, the configuration-based SDK has no equivalent for MethodPairInstrumentation used in autotrace
  • Capturing all arguments or the return value without explicitly creating a tag is not supported.
  • Specifying name patterns for classes or methods is not supported.
  • Restoring a trace context before creating a span is not supported