dynatrace / oneagent-sdk-for-dotnet

Enables custom tracing of .NET applications in Dynatrace

Dynatrace OneAgent SDK for .NET

This SDK allows Dynatrace customers to instrument .NET applications. This is useful to enhance the visibility for proprietary frameworks or custom frameworks not directly supported by Dynatrace OneAgent out-of-the-box.

This is the official .NET implementation of the Dynatrace OneAgent SDK.

Table of Contents

• Package contents
• Requirements
• Integration
  • Dependencies
  • Troubleshooting
• API Concepts
  • IOneAgentSDK object
  • Trace Context
  • Tracers
• Features
  • Trace SQL database requests
  • Trace remote calls
  • Trace messaging
  • Trace web requests
  • In-process linking
  • Add custom request attributes
  • Logging callback
  • SdkState and IOneAgentInfo
• Further reading
• Help & Support
• Release notes

Package contents

• samples: sample application which demonstrates the usage of the SDK
• src: source code of the SDK (API and implementation stub - for reference only, not intended to be edited/extended/built by the user)
• LICENSE: license under which the SDK and sample applications are published

The SDK implementation is provided by the installed OneAgent at runtime. The classes in src/DummyImpl are a stub that is used if no OneAgent is installed on the host so that your application is not affected by any missing OneAgent dependency.

Requirements

• Dynatrace OneAgent (required versions see below)
• .NET Full Framework >= 4.5 or .NET Core >= 1.0 (the SDK is built using .NET Standard 1.0)

OneAgent SDK for .NET	Required OneAgent version	Support status
1.8.0	>=1.233	Supported
1.7.0	>=1.179	Supported
1.6.0	>=1.173	Supported
1.5.0	>=1.171	Supported
1.4.0	>=1.167	Supported
1.3.0	>=1.165	Supported
1.2.0	>=1.161	Supported
1.1.0	>=1.157	Supported
1.0.0-alpha	1.153-1.155	EAP (not supported)

Integration

Using this SDK should not cause any errors if no OneAgent is present (e.g. in testing).

Dependencies

If you want to integrate the OneAgent SDK into your application, just add the following NuGet dependency:

Dynatrace.OneAgent.Sdk NuGet package

The Dynatrace OneAgent SDK for .NET has no further dependencies.

Troubleshooting

Make sure that:

• OneAgent is installed on the host running your application
• the installed version of OneAgent is compatible with the SDK version you are using (see Requirements, check using SdkState and IOneAgentInfo)
• process monitoring is enabled in Dynatrace
• you have set the OneAgent SDK logging callback and check its output

Also note that injection of the OneAgent code module will not work if you start your application from within Visual Studio. In that case the SDK will behave as if OneAgent is not installed. If you need to debug your application with the code module injected, you can start the application from Explorer or cmd.exe and then attach Visual Studio as debugger to the running process (Debug -> Attach to Process...).

API Concepts

Common concepts of the Dynatrace OneAgent SDK are explained the Dynatrace OneAgent SDK repository.

IOneAgentSdk object

Use OneAgentSdkFactory.CreateInstance to obtain an instance of IOneAgentSDK, which is used to create tracers and info objects. You should reuse this object over the whole application and if possible CLR lifetime:

IOneAgentSdk oneAgentSdk = OneAgentSdkFactory.CreateInstance();

Trace Context

An instance of the OneAgentSDK can be used to get the current ITraceContextInfo which holds information about the Trace-Id and Span-Id of the current PurePath node. This information can then be used to provide e.g. additional context in log messages.

Please note that TraceContextInfo is not intended for tagging or context-propagation use cases. Dedicated APIs (e.g. remote calls or web requests) as well as built-in OneAgent sensors take care of linking services correctly.

ITraceContextInfo traceContextInfo = oneAgentSdk.TraceContextInfo;
string traceId = traceContextInfo.TraceId;
string spanId = traceContextInfo.SpanId;
_logger.LogInformation($"[!dt dt.trace_id={traceId},dt.span_id={spanId}] sending request ...");

Tracers

To trace any kind of call you first need to create a Tracer. The Tracer object represents the logical and physical endpoint that you want to call. A Tracer serves two purposes. First to time the call (duration, cpu and more) and report errors. That is why each Tracer has these four methods. Either one of the Error methods must be called at most once, and it must be in between Start and End. Each Tracer can only be used once and you need to create a new instance for each request/call that you want to trace (i.e., Start cannot be called twice on the same instance).

void Start();

void Error(Exception exception);

void Error(String message);

void End();

The Start method only supports synchronous methods (in other words C# methods without the async keyword). If you call Start() in an async method, then with high probability the SDK won't capture the specific data.

Sample usage:

public static async Task SampleMethodAsync()
{
    IOneAgentSdk oneAgentSdk = OneAgentSdkFactory.CreateInstance();
    IDatabaseInfo dbInfo = oneAgentSdk.CreateDatabaseInfo("MyDb", "MyVendor", ChannelType.TCP_IP, "database.example.com:1234");
    IDatabaseRequestTracer dbTracer = oneAgentSdk.TraceSQLDatabaseRequest(dbInfo, "Select * From AA");

    await dbTracer.Start();
    try
    {
        DatabaseApi.DatabaseCall();
    }
    catch (Exception e)
    {
        dbTracer.Error(e);
        // handle or rethrow
    }
    finally
    {
        dbTracer.End();
    }
}

Note: Previous versions of the OneAgent SDK supported tracing of asynchronous methods (which are C# methods that are marked with the async keyword) using the method StartAsync(). This method has been removed for technical reasons and the way of tracing asynchronous code is the TraceAsync method (see below).

The SDK also offers a convenient Trace method. This method can be called in both asynchronous and synchronous methods. In case of an async method you can pass the given async method to the TraceAsync method and await on the result of the TraceAsync method.

void Trace(Action action);

T Trace<T>(Func<T> func);

Task TraceAsync(Func<Task> func);

Task<T> TraceAsync<T>(Func<Task<T>> func);

Sample usage:

public static async Task SampleMethodAsync()
{
    IOneAgentSdk oneAgentSdk = OneAgentSdkFactory.CreateInstance();
    IDatabaseInfo dbInfo = oneAgentSdk.CreateDatabaseInfo("MyDb", "MyVendor", ChannelType.TCP_IP, "database.example.com:1234");
    IDatabaseRequestTracer dbTracer = oneAgentSdk.TraceSQLDatabaseRequest(dbInfo, "Select * From AA");

    var result = await dbTracer.TraceAsync(() => DatabaseApi.AsyncDatabaseCall());
}

The Trace method internally calls the Start method. In case of an exception it also calls the Error method and it finally calls the End method.

To summarize this, in case of

• synchronous methods you should use the Trace method but can also use the Start, End and Error methods
• asynchronous methods you can use the TraceAsync method.

NOTE: Due to internal limitations TraceAsync does not currently reliably connect child nodes. If there are child nodes started during a call to TraceAsync, they might be connected to the parent of the TraceAsync, if any, might become separate root paths, or might be suppressed entirely.

Consider using Trace as a workaround, but note that asynchronous parts of the execution after Trace returns will not be tracked by the node created by Trace. In particular, exceptions thrown in the asynchronous part (approximately after Trace returns) are potentially missed.

Some tracers offer methods to provide information in addition to the parameters required for creating the tracer using the IOneAgentSdk object. These additional pieces of information might be relevant for service detection and naming. If this is the case, they can only be set before starting the tracer as stated in the respective method documentation. After ending a tracer, it must not be used any longer. Since none of its methods must be called, no further information can be provided to an ended tracer.

To allow tracing across process and technology boundaries, tracers can be supplied with so-called tags. Tags are strings or byte arrays generated by the SDK that enable Dynatrace to trace a transaction end-to-end. The user has to take care of transporting the tag from one process to the other.

Features

The feature sets differ slightly with each language implementation. More functionality will be added over time, see Planned features for OneAgent SDK for details on upcoming features.

A more detailed specification of the features can be found in Dynatrace OneAgent SDK.

Feature	Required OneAgent SDK for .NET version
ITraceContextInfo	>=1.8.0
Support for W3C Trace Context (IOutgoingWebRequestTracer.InjectTracingHeaders)	>=1.6.0
Trace incoming web requests	>=1.5.0
Trace outgoing web requests	>=1.4.0
Custom request attributes	>=1.4.0
In-process linking, SdkState and IOneAgentInfo	>=1.3.0
Trace messaging	>=1.2.0
Trace remote calls	>=1.1.0
Logging callback	>=1.1.0
Trace SQL database requests	>=1.0.0-alpha

Trace SQL database requests

A SQL database request is traced by calling TraceSQLDatabaseRequest. See DatabaseRequestTracerSamples.cs for the full list of examples (sync/async/lambda/exception/...)

Example of a synchronous database call (see DatabaseRequestTracerSamples.cs for more details):

IDatabaseInfo dbInfo = oneAgentSdk.CreateDatabaseInfo("MyDb", "MyVendor", ChannelType.TCP_IP, "database.example.com:1234");
IDatabaseRequestTracer dbTracer = oneAgentSdk.TraceSQLDatabaseRequest(dbInfo, "Select * From AA");

dbTracer.Trace(() => ExecuteDbCallVoid());

Example of tracing database call in an async lambda expression (see DatabaseRequestTracerSamples.cs for more details):

IDatabaseInfo dbInfo = oneAgentSdk.CreateDatabaseInfo("MyDb", "MyVendor", ChannelType.TCP_IP, "database.example.com:1234");
IDatabaseRequestTracer dbTracer = oneAgentSdk.TraceSQLDatabaseRequest(dbInfo, "Select * From AA");

int res = dbTracer.Trace(() => ExecuteDbCallInt());

See also our initial blog post about the OneAgent SDK for .NET, which shows how databases can be traced using the IDatabaseRequestTracer and how these traces are presented and analyzed in Dynatrace: Extend framework support with OneAgent SDK for .NET

Please note that SQL database traces are only created if they occur within some other SDK trace (e.g. incoming remote call) or a OneAgent built-in trace (e.g. incoming web request).

Trace remote calls

You can use the SDK to trace proprietary IPC communication from one process to the other. This will enable you to see full Service Flow, PurePath and Smartscape topology for remoting technologies that Dynatrace is not aware of.

To trace any kind of remote call you first need to create a Tracer. The Tracer object represents the endpoint that you want to call, as such you need to supply the name of the remote service and remote method. In addition you need to transport the tag in your remote call to the server side if you want to trace it end-to-end.

IOutgoingRemoteCallTracer outgoingRemoteCallTracer = oneAgentSdk.TraceOutgoingRemoteCall(
    "RemoteMethod", "RemoteServiceName",
    "mrcp://endpoint/service", ChannelType.TCP_IP, "myRemoteHost:1234");
outgoingRemoteCallTracer.SetProtocolName("MyRemoteCallProtocol");

outgoingRemoteCallTracer.Start();
try
{
    string tag = outgoingRemoteCallTracer.GetDynatraceStringTag();
    // make the call and transport the tag across to the server to link both sides of the remote call together
}
catch (Exception e)
{
    outgoingRemoteCallTracer.Error(e);
    // handle or rethrow
}
finally
{
    outgoingRemoteCallTracer.End();
}

On the server side you need to wrap the handling and processing of your remote call as well. This will not only trace the server side call and everything that happens, it will also connect it to the calling side.

IIncomingRemoteCallTracer incomingRemoteCallTracer = oneAgentSdk
    .TraceIncomingRemoteCall("RemoteMethod", "RemoteServiceName", "mrcp://endpoint/service");

string incomingDynatraceStringTag = ...; // retrieve from incoming call metadata
 // link both sides of the remote call together
incomingRemoteCallTracer.SetDynatraceStringTag(incomingDynatraceStringTag);
incomingRemoteCallTracer.SetProtocolName("MyRemoteCallProtocol");

incomingRemoteCallTracer.Start();
try
{
    ProcessRemoteCall();
}
catch (Exception e)
{
    incomingRemoteCallTracer.Error(e);
    // handle or rethrow
}
finally
{
    incomingRemoteCallTracer.End();
}

Trace messaging

You can use the SDK to trace messages sent or received via messaging & queuing systems. When tracing messages, we distinguish between:

• sending a message
• receiving a message
• processing a received message

To trace an outgoing message, you need to create an IMessagingSystemInfo and call TraceOutgoingMessage with that instance:

string serverEndpoint = "messageserver.example.com:1234";
string topic = "my-topic";
IMessagingSystemInfo messagingSystemInfo = oneAgentSdk
    .CreateMessagingSystemInfo("MyCustomMessagingSystem", topic, MessageDestinationType.TOPIC, ChannelType.TCP_IP, serverEndpoint);

IOutgoingMessageTracer outgoingMessageTracer = oneAgentSdk.TraceOutgoingMessage(messagingSystemInfo);

outgoingMessageTracer.Start();
try
{
    Message message = new Message();
    message.CorrelationId = "my-correlation-id-1234"; // optional, determined by application

    // transport the Dynatrace tag along with the message to allow the outgoing message tracer to be linked
    // with the message processing tracer on the receiving side
    message.Headers[OneAgentSdkConstants.DYNATRACE_MESSAGE_PROPERTYNAME] = outgoingMessageTracer.GetDynatraceByteTag();

    SendResult result = MyMessagingSystem.SendMessage(message);

    outgoingMessageTracer.SetCorrelationId(message.CorrelationId);    // optional
    outgoingMessageTracer.SetVendorMessageId(result.VendorMessageId); // optional
}
catch (Exception e)
{
    outgoingMessageTracer.Error(e);
    // handle or rethrow
    throw e;
}
finally
{
    outgoingMessageTracer.End();
}

On the incoming side, we need to differentiate between the blocking receiving part and processing the received message. Therefore two different tracers are used: IIncomingMessageReceiveTracer and IIncomingMessageProcessTracer.

string serverEndpoint = "messageserver.example.com:1234";
string topic = "my-topic";
IMessagingSystemInfo messagingSystemInfo = oneAgentSdk
    .CreateMessagingSystemInfo("MyCustomMessagingSystem", topic, MessageDestinationType.TOPIC, ChannelType.TCP_IP, serverEndpoint);

IIncomingMessageReceiveTracer receiveTracer = oneAgentSdk.TraceIncomingMessageReceive(messagingSystemInfo);

receiveTracer.Start();
try
{
    // blocking call until message is available:
    ReceiveResult receiveResult = MyMessagingSystem.ReceiveMessage();
    Message message = receiveResult.Message;

    IIncomingMessageProcessTracer processTracer = oneAgentSdk.TraceIncomingMessageProcess(messagingSystemInfo);

    // retrieve Dynatrace tag created using the outgoing message tracer to link both sides together:
    if (message.Headers.ContainsKey(OneAgentSdkConstants.DYNATRACE_MESSAGE_PROPERTYNAME))
    {
        processTracer.SetDynatraceByteTag(message.Headers[OneAgentSdkConstants.DYNATRACE_MESSAGE_PROPERTYNAME]);
    }
    // start processing:
    processTracer.Start();
    processTracer.SetCorrelationId(message.CorrelationId);           // optional
    processTracer.SetVendorMessageId(receiveResult.VendorMessageId); // optional
    try
    {
        ProcessMessage(message); // do the work ...
    }
    catch (Exception e)
    {
        processTracer.Error(e);
        // handle or rethrow
        throw e;
    }
    finally
    {
        processTracer.End();
    }
}
catch (Exception e)
{
    receiveTracer.Error(e);
    // handle or rethrow
    throw e;
}
finally
{
    receiveTracer.End();
}

In case of a non-blocking receive (e.g. via an event handler), there is no need to use IIncomingMessageReceiveTracer - just trace processing of the message by using the IIncomingMessageProcessTracer:

void OnMessageReceived(ReceiveResult receiveResult)
{
    string serverEndpoint = "messageserver.example.com:1234";
    string topic = "my-topic";
    IMessagingSystemInfo messagingSystemInfo = oneAgentSdk
        .CreateMessagingSystemInfo("MyCustomMessagingSystem", topic, MessageDestinationType.TOPIC, ChannelType.TCP_IP, serverEndpoint);

    Message message = receiveResult.Message;

    IIncomingMessageProcessTracer processTracer = oneAgentSdk.TraceIncomingMessageProcess(messagingSystemInfo);

    // retrieve Dynatrace tag created using the outgoing message tracer to link both sides together:
    if (message.Headers.ContainsKey(OneAgentSdkConstants.DYNATRACE_MESSAGE_PROPERTYNAME))
    {
        processTracer.SetDynatraceByteTag(message.Headers[OneAgentSdkConstants.DYNATRACE_MESSAGE_PROPERTYNAME]);
    }
    // start processing:
    processTracer.Start();
    processTracer.SetCorrelationId(message.CorrelationId);           // optional
    processTracer.SetVendorMessageId(receiveResult.VendorMessageId); // optional
    try
    {
        ProcessMessage(message); // do the work ...
    }
    catch (Exception e)
    {
        processTracer.Error(e);
        // handle or rethrow
        throw e;
    }
    finally
    {
        processTracer.End();
    }
}

See also:

• The documentation on messaging tracers in the specification repository.
• This blog post explaining end-to-end tracing for additional message queues with the OneAgent SDK .

Trace web requests

Trace outgoing web requests

You can use the SDK to trace outgoing web requests. This allows tracing web requests performed using HTTP client libraries which are not supported by the Dynatrace OneAgent out-of-the-box. Always include the Dynatrace header with the request as it is required to match the request on the server side. This ensures requests are traced end-to-end when the server is monitored using a OneAgent or OneAgent SDK.

IOutgoingWebRequestTracer tracer = SampleApplication.OneAgentSdk.TraceOutgoingWebRequest(request.Url, request.Method);

foreach (KeyValuePair<string, string> header in request.Headers)
{
    tracer.AddRequestHeader(header.Key, header.Value);
}

await tracer.TraceAsync(async () =>
{
    // add the Dynatrace tag or W3C Trace Context (based on your configuration) to request headers to allow
    // the agent in the web server to link the request together for end-to-end tracing
    tracer.InjectTracingHeaders((key, value) => request.Headers[key] = value);

    MyCustomHttpResponse response = await request.ExecuteAsync();

    tracer.SetStatusCode(response.StatusCode);

    foreach (KeyValuePair<string, string> header in response.Headers)
    {
        tracer.AddResponseHeader(header.Key, header.Value);
    }
});

Trace incoming web requests

You can use the SDK to trace incoming web requests. This might be useful if Dynatrace does not support the web server framework or language processing the incoming web requests.

To trace an incoming web request you first need to create an IWebApplicationInfo object. This info object represents the endpoint of your web server (web server name, application name and context root; see our documentation for further information). This object should be reused for all traced web requests within the same application.

IWebApplicationInfo webAppInfo =
    oneAgentSdk.CreateWebApplicationInfo("WebShopProduction", "AuthenticationService", "/api/auth");
//                                       Web server name      Application ID           Context Root

To trace an incoming web request you then need to create a Tracer object. Make sure you provide all HTTP headers from the request to the SDK by calling AddRequestHeader. This allows both sides of the web requests to be linked together for end-to-end tracing.

IIncomingWebRequestTracer tracer = oneAgentSdk.TraceIncomingWebRequest(webAppInfo, request.Url, request.Method);
tracer.SetRemoteAddress(request.RemoteClientAddress);

// adding all request headers ensures that tracing headers required
// for end-to-end linking of requests are provided to the SDK
foreach (KeyValuePair<string, string> header in request.Headers)
{
    tracer.AddRequestHeader(header.Key, header.Value);
}
foreach (KeyValuePair<string, string> param in request.PostParameters)
{
    tracer.AddParameter(param.Key, param.Value);
}

// start tracer
return tracer.Trace(() =>
{
    // handle request and build response ...

    foreach (KeyValuePair<string, string> header in response.Headers)
    {
        tracer.AddResponseHeader(header.Key, header.Value);
    }
    tracer.SetStatusCode(response.StatusCode);

    return response;
});

In-process linking

In order to trace interactions between different threads, so-called in-process links are used. An in-process link is created on the originating thread and then used for creating an IInProcessLinkTracer on the target thread.

Calls detected while the tracer is active (i.e., between Start and End or within any of the Trace methods) are traced as part of the originating service call. This works for calls detected out-of-the-box by the OneAgent as well as calls traced using the OneAgent SDK.

// create an in-process link on the originating thread
IInProcessLink inProcessLink = oneAgentSdk.CreateInProcessLink();

// delegate work to another thread, in this case we use a custom background worker implementation
customBackgroundWorker.EnqueueWorkItem(() =>
{
    // use the in-process link to link the PurePath on the target thread to its origin
    IInProcessLinkTracer inProcessLinkTracer = oneAgentSdk.TraceInProcessLink(inProcessLink);
    inProcessLinkTracer.Start();
    // processing and performing further calls...
    inProcessLinkTracer.End();

    // calls executed after ending the IInProcessLinkTracer will
    // *not* be traced as part of the originating service call
});

Note that you can re-use in-process links to create multiple in-process link tracers.

Add custom request attributes

You can use the SDK to add custom request attributes to the currently traced service call. These attributes (key-value pairs) can be used to search and filter requests in Dynatrace.

In order to add a custom request attribute, the AddCustomRequestAttribute methods are used. No reference to a tracer is needed as OneAgent SDK will select the currently active PurePath. This may be a PurePath created by OneAgent SDK or a PurePath created by built-in sensors of the OneAgent. The methods take two arguments - a key, specifying the name of the attribute, and a value, which can be either a string, long or double. These methods can be called several times to add multiple attributes to the same request. If the same attribute key is used several times, all values will be recorded.

oneAgentSdk.AddCustomRequestAttribute("region", "EMEA");
oneAgentSdk.AddCustomRequestAttribute("salesAmount", 2500);
oneAgentSdk.AddCustomRequestAttribute("service-quality", 0.707106);

oneAgentSdk.AddCustomRequestAttribute("account-group", 1);
oneAgentSdk.AddCustomRequestAttribute("account-group", 2);
oneAgentSdk.AddCustomRequestAttribute("account-group", 3);

If no service call is currently being traced, the attributes will be discarded. Therefore, for calls traced with OneAgent SDK, custom request attributes have to be added after starting the tracer (or from within an ITracer.Trace method) in order to have an active PurePath.
Strings exceeding the lengths specified here will be truncated.

See also our blog post explaining how custom request attributes are configured, displayed and analyzed in Dynatrace: Capture any request attributes using OneAgent SDK

Logging callback

The SDK provides a logging-callback to give information back to the calling application in case of an error. The user application has to provide a callback like the following:

class StdErrLoggingCallback : ILoggingCallback
{
    public void Error(string message) => Console.Error.WriteLine("[OneAgent SDK] Error:   " + message);
    public void Warn (string message) => Console.Error.WriteLine("[OneAgent SDK] Warning: " + message);
}

public static void Main(string[] args)
{
    IOneAgentSdk oneAgentSdk = OneAgentSdkFactory.CreateInstance();
    var loggingCallback = new StdErrLoggingCallback();
    oneAgentSdk.SetLoggingCallback(loggingCallback);
}

In general it is a good idea to forward these logging events to your application specific logging framework.

SdkState and IOneAgentInfo

For troubleshooting and avoiding any ineffective tracing calls you can check the state of the SDK as follows:

IOneAgentSdk oneAgentSdk = OneAgentSdkFactory.CreateInstance();
SdkState state = oneAgentSdk.CurrentState;
switch (state)
{
    case SdkState.ACTIVE:               // SDK ready for use
    case SdkState.TEMPORARILY_INACTIVE: // capturing disabled, tracing calls can be spared
    case SdkState.PERMANENTLY_INACTIVE: // SDK permanently inactive, tracing calls can be spared
}

It is good practice to check the SDK state regularly as it may change at every point of time (except PERMANENTLY_INACTIVE, which never changes over application lifetime).

Information about the OneAgent used by the SDK can be retrieved using IOneAgentInfo:

IOneAgentSdk oneAgentSdk = OneAgentSdkFactory.CreateInstance();
IOneAgentInfo agentInfo = oneAgentSdk.AgentInfo;
if (agentInfo.AgentFound)
{
    Console.WriteLine($"OneAgent Version: {agentInfo.Version}");
    if (agentInfo.AgentCompatible)
    {
        // agent is fully compatible with current SDK version
    }
}

See SdkState.cs and IOneAgentInfo.cs for further information.

Further readings

• What is the OneAgent SDK? in the Dynatrace documentation
• Feedback & Roadmap thread in AnswerHub

Help & Support

Support policy

The Dynatrace OneAgent SDK for .NET has GA status. The features are fully supported by Dynatrace.

For detailed support policy see Dynatrace OneAgent SDK help.

Get Help

• Ask a question in the product forums
• Read the product documentation

Open a GitHub issue to

• Report minor defects, minor items or typos
• Ask for improvements or changes in the SDK API
• Ask any questions related to the community effort

SLAs don't apply for GitHub tickets

Customers can open a ticket on the Dynatrace support portal to

• Get support from the Dynatrace technical support engineering team
• Manage and resolve product-related technical issues

SLAs apply according to the customer's support level.

Release Notes

see also Releases

Version	Description
1.8.0	Removes deprecated APIs and types. Adds TraceContextInfo.
1.7.1	Deprecates metrics-related types and APIs
1.7.0	Adds metrics support (preview only) and deprecates ITracer.StartAsync API method
1.6.0	Adds W3C Trace Context support (IOutgoingWebRequestTracer.InjectTracingHeaders)
1.5.0	Adds incoming web request tracing
1.4.0	Adds custom request attributes and outgoing web request tracing
1.3.0	Adds in-process linking, ITracer.Error(Exception), SdkState and IOneAgentInfo
1.2.0	Adds message tracing
1.1.0	First GA release - starting with this version OneAgent SDK for .NET is now officially supported by Dynatrace
1.1.0-alpha	Adds remote call tracing and logging callback
1.0.0-alpha	EAP release

oneagent-sdk-for-dotnet's Issues

traceCustomService - not implemented

Hi,

Seems like the traceCustomService was not implemented in the .NET SDK.
(I was able to find and use it on the JAVA SDK)

Daniel

How to configure Dynatrace for custom request attribute tracing

Sorry to ask this question here but not sure how else to reach out in order to hopefully get a quick response. We have spent weeks on this already and feeling "my neck is on the line" if it takes much longer... You will also need better guide for when this feature lands in the SDK in any case

Trying to follow guide for How do I capture request attributes based on .NET method arguments?

This post and the one for Web post start off with:

1. Go to Settings > Server-side monitoring > Request attributes.

However I can't seem to find that in my Dynatrace client. Is this controlled from the server side (where I don't have direct access)? or is it because the UI and interface/menus change between versions (I have Dynatrace 7 from 2017)

Would be great if you could add more screenshots to these step-by-step guides. Feeling lost.

Thank you so much!

TraceOutgoingRemoteCall StartAsync deprecated

As stated in documentation the StartAsync method is deprecated.
I want to use the TraceAsync, but is a bit confused on how to retrieve the Tag when TraceAsync requires an action. My action is a RPC and the tag is a prerequisite to that.

Consider this:

`
IOutgoingRemoteCallTracer outgoingRemoteCallTracer = oneAgentSdk.TraceOutgoingRemoteCall(
"RemoteMethod", "RemoteServiceName",
"mrcp://endpoint/service", ChannelType.TCP_IP, "myRemoteHost:1234");
outgoingRemoteCallTracer.SetProtocolName("MyRemoteCallProtocol");

try
{
string tag = outgoingRemoteCallTracer.GetDynatraceStringTag();
outgoingRemoteCallTracer.TraceAsync(_client.RpcCall(tag));
}
catch (Exception e)
{
outgoingRemoteCallTracer.Error(e);
// handle or rethrow
}
finally
{
outgoingRemoteCallTracer.End();
}
`
Currently we are using the StartAsync and supressing the deprecated log message.

Cant create an instance of OneAgentSdk factory

I am having issue creating an instance of OneAgentSdkFactory. While compiling the code I am getting the error "Reference to type 'Object' claims it is defined in 'System.Runtime', but it could not be found".

How I reach this point> I just installed the nuget package to my solution and tried to use the api following the example stated in the hub.

DatabaseRequestTracer StartAsync deprecated

How do I write an Entity Framework Core interceptor if I don't have StartAsync?

Right now I inherit from DbCommandInterceptor and override e.g.

        public override async Task<InterceptionResult<DbDataReader>> ReaderExecutingAsync(DbCommand command, CommandEventData eventData, InterceptionResult<DbDataReader> result, CancellationToken cancellationToken = new CancellationToken())
        {
            await StartAsync(command).ConfigureAwait(false);
            return await base.ReaderExecutingAsync(command, eventData, result, cancellationToken).ConfigureAwait(false);
        }

        public override async Task<DbDataReader> ReaderExecutedAsync(DbCommand command, CommandExecutedEventData eventData, DbDataReader result, CancellationToken cancellationToken = new CancellationToken())
        {
            var reader = await base.ReaderExecutedAsync(command, eventData, result, cancellationToken).ConfigureAwait(false);
            Stop(command);

            return reader;
        }

How do I do that when StartAsync() has disappeared?

Please add the ability to get the process_group_instance id

Is your feature request related to a problem? Please describe.
We are using Azure App Services with the Dynatrace One Agent Site Extension. The problem is that this version of the OneAgent doesn't support autodiscovery of logs. So to get the logs out, we have written our own logger which sends the logs to the /ingest endpoint. We're using this SDK to get the TraceId and the SpanId to populate into the logs. But we can't find a way to programmatically get the process_group_instance id to properly link the logs to the service in Dynatrace.

Describe the solution you'd like
In the same way that the dynatraceSdk.TraceContextInfo exposes the TraceId and the SpanId, I'd love for it to expose the process group id.

Describe alternatives you've considered
We could manually look up the process group id in dynatrace and then add extra configuration to our logger, but we've got hundreds of services that occasionally change how they're detected in Dynatrace. It would be a lot of work and quite flakey to do this manually.

Additional context
Alternatively, I think Dynatrace already knows which process group was assigned to a given traceid, so maybe there is a Dynatrace logs ingest backend-fix where it could lookup the missing id and populate it?

IOutgoingMessageTracer.GetDynatraceStringTag() return string.Empty

Hi,
I'm trying to do a PoC with the message tracer and when I try to get the string tag I only get an empty string, Could you tell me why?
I think I'am missing something here, I've cheched the source code of the SDK and there is only a Dummy Implementation with no code.
Could you gime some advice?
Thanks in advance.
Facundo

How to trace IAsyncEnumerable calls

The current ITrace API has Trace(Func<T> func) and TraceAsync(Func<Task<T>> func), but none of these two can trace an IAsyncEnumerable call. It would be possible to do it with the now-obsolete StartAsync method, eg.:

_tracer.StartAsync();
try 
{
  await foreach (var item in items)
  {
    yield return item;
  }
}
catch (Exception ex)
{
  _tracer.Error(ex);
}
finally
{
  _tracer.End();
}

Though I'm not even sure if this would be the best implementation, since it would also take into consideration the time the caller took to do whatever computation with the streamed items.

The current alternative is to just _tracer.Trace(MethodThatReturnsIAsyncEnumerable), but this also has its drawbacks, namely that it will only trace the call that starts the streaming, but will not track the streaming itself. For example, if an error occurs while streaming from the database, the tracer will not catch that.

Tracing async WCF calls

Hi,

I have a question about tracing async calls to the WCF server.
For some time now we were using IClientMessageInspector to track requests, starting trace and adding dynatrace header in BeforeSendRequest and stopping tracer in AfterReceiveReply. It works perfectly fine for synchronous API, but for asynchronous the behavior is unpredictable.
I've read in readme that Start/End is not supposed to be used in async flow, so I expect it to cause that issue as BeforeSendRequest and AfterReceiveReply might be performed on different threads.

I know you provide TrackAsync method, but it's not possible to wrap these two methods mentioned above, as they are invoked by WCF.
How should I approach this problem?

Please improve tagging capability and SDK docs

Currently resorting to looking at the tests or code samples

But is all just "dummy" stuff.

Had hoped I had found sth useful. Where can I find docs of what is currently available (as per 1.2) and how to use it. More interested in the IncomingRemoteCallTracer

Had hope we could somehow tag with applicationId or sth useful

incomingRemoteCallTracer.SetDynatraceStringTag(applicationId);

Turns out this is limited to connecting outgoing and incoming request tracing via "bonding" on a DynaTrace generated tag from what I can gather from sample app.

Really hoping for sth like custom request attributes ASAP: https://www.dynatrace.com/news/blog/capture-any-request-attributes-using-oneagent-sdk/

My boss wants some progress on this task, but I am completely blocked by current SDK limitations and lack of docs.

Hope you can give some advice for how to proceed. Perhaps using a DynaTrace HTTPS/REST API directly? Is this what the SDK is using internally or is it a proprietary protocol?