Configuration-based .NET Core Trace SDK
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, 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 Core 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 Core 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 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,
set the environment-variable INSTANA_NETCORE_SDKCONFIG
to 1
in order to enable it. Version >= 1.193.4 do not need this switch anymore.
Format
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.
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 classname
: Fully qualified name of the class, interface or base class to match
For nested classes, the notationa.b.c.OutsideClass$NestedClass
is expectedmethod
: Name of the method of the given class, interface or base class of which an invocation should be recordedarguments
: 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 nametype
: Span type (optional); supported values:ENTRY
, used to indicate "incoming" calls from external systemsINTERMEDIATE
, 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 valuekind
:constant
name
: Name of the tag to createvalue
: Constant value of the tag to create
return
, capture the return value of the method invocationkind
: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 invocationkind
:argument
name
: Name of the tag to createindex
: 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 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
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