Configuration-based .NET Core Trace SDK
TABLE OF CONTENTS
The configuration-based .NET Core 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, please read the tracing best practices.
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 Core SDK, which is far more resilient against code changes and has more features to help you accomplish your goals.
The configuration is specified in the
NOTE: Changes to the configuration of the configuration-based .NET Core Trace SDK are automatically picked up by the Instana agent. Already instrumented applications need to be restarted to use the changed configuration.
NOTE: The configuration based .NET Core Trace SDK is available in the Nuget packages version
1.191.20 and .NET Core sensor
1.0.28 or above. With nuget-package versions prior to 1.193.4 it is an opt-in feature. To enable it, please set the environment-variable
1 in order to enable it. Version >= 1.193.4 do not need this switch anymore.
The following listing describes the general format of the configuration:
# .NET Full Framework Tracing com.instana.plugin.netcore: 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.
match object of one
target specifies the method to apply the instrumentation to.
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.
NOTE: 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
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.
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
name: Name of the tag to create
value: Constant value of the tag to create
return, capture the return value of the method invocation
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
name: Name of the tag to create
index: 0-based index of the argument to capture as value of the tag
NOTE: If the captured value is
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
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
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
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
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
The following restrictions apply to the configuration-based .NET Core 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
MethodPairInstrumentationused in autotrace
- Capturing all arguments or the return value without explicitly creating a
tagis not supported.
- Specifying name patterns for classes or methods is not supported.
- Restoring a trace context before creating a span is not supported