ITransaction

Syntax

public interface ITransaction

Provides access to transaction-specific methods in the New Relic API.

Description

Provides access to transaction-specific methods in the New Relic .NET agent API. To obtain a reference to ITransaction, use the current transaction method available on IAgent.

The following methods are available on ITransaction:

AcceptDistributedTraceHeaders

ITransaction.AcceptDistributedTraceHeaders is used to instrument the called service for inclusion in a distributed trace. It links the spans in a trace by accepting a payload generated by InsertDistributedTraceHeaders or generated by some other W3C Trace Context compliant tracer. This method accepts the headers of an incoming request, looks for W3C Trace Context headers, and if not found, falls back to New Relic distributed trace headers. This method replaces the deprecated AcceptDistributedTracePayload method, which only handles New Relic distributed trace payloads.

Syntax

void AcceptDistributedTraceHeaders(carrier, getter, transportType)

Parameters

Usage considerations

• Distributed tracing must be enabled.
• AcceptDistributedTraceHeaders will be ignored if InsertDistributedTraceHeaders or AcceptDistributedTraceHeaders has already been called for this transaction.

Example

HttpContext httpContext = HttpContext.Current;
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;
currentTransaction.AcceptDistributedTraceHeaders(httpContext, Getter, TransportType.HTTP);
IEnumerable<string> Getter(HttpContext carrier, string key) 
{ 
    string value = carrier.Request.Headers[key];   
    return value == null ? null : new string[] { value }; 
}

InsertDistributedTraceHeaders

ITransaction.InsertDistributedTraceHeaders is used to implement distributed tracing. It modifies the carrier object that is passed in by adding W3C Trace Context headers and New Relic Distributed Trace headers. The New Relic headers can be disabled with <distributedTracing excludeNewrelicHeader="true" /> in the config. This method replaces the deprecated CreateDistributedTracePayload method, which only creates New Relic Distributed Trace payloads.

Syntax

void InsertDistributedTraceHeaders(carrier, setter)

Parameters

Usage considerations

• Distributed tracing must be enabled.

Example

HttpWebRequest requestMessage = (HttpWebRequest)WebRequest.Create("https://remote-address");
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;
var setter = new Action<HttpWebRequest, string, string>((carrier, key, value) => { carrier.Headers?.Set(key, value); });
currentTransaction.InsertDistributedTraceHeaders(requestMessage, setter);

AcceptDistributedTracePayload

Accepts an incoming distributed trace payload from an upstream service. Calling this method links the transaction from the upstream service to this transaction.

Syntax

void AcceptDistributedPayload(payload, transportType)

Parameters

Usage considerations

• Distributed tracing must be enabled.
• The payload can be a Base64-encoded or plain text string.
• AcceptDistributedTracePayload will be ignored if CreateDistributedTracePayload has already been called for this transaction.

Example

//Obtain the information from the request object from the upstream caller.
//The method by which this information is obtain is specific to the transport 
//type being used. For example, in an HttpRequest, this information is
//contained in the 
header.KeyValuePair<string, string> metadata = GetMetaDataFromRequest("requestPayload");
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); 
ITransaction transaction = agent.CurrentTransaction; 
transaction.AcceptDistributedTracePayload(metadata.Value, TransportType.Queue);

CreateDistributedTracePayload (obsolete)

Creates a distributed trace payload for inclusion in an outgoing request to a downstream system.

Syntax

IDistributedTracePayload CreateDistributedTracePayload()

Returns

An object that implements IDistributedTracePayload which provides access to the distributed trace payload that was created.

Usage considerations

• Distributed tracing must be enabled.
• CreateDistributedTracePayload will be ignored if AcceptDistributedTracePayload has already been called for this transaction.

Example

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
IDistributedTracePayload payload = transaction.CreateDistributedTracePayload();

AddCustomAttribute

Adds contextual information about your application to the current transaction in the form of attributes.

This method requires .NET agent version and .NET agent API version 8.24.244.0 or higher. It replaced the deprecated AddCustomParameter.

Syntax

ITransaction AddCustomAttribute(string key, object value)

Parameters

Returns

A reference to the current transaction.

Usage considerations

For details about supported data types, see the Custom Attributes Guide.

Example

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
transaction.AddCustomAttribute("customerName","Bob Smith")
    .AddCustomAttribute("currentAge",31)
    .AddCustomAttribute("birthday", new DateTime(2000, 02, 14))
    .AddCustomAttribute("waitTime", TimeSpan.FromMilliseconds(93842));

CurrentSpan

Provides access to the currently executing span, making span-specific methods available within the New Relic API.

Example

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); 
ITransaction transaction = agent.CurrentTransaction; 
ISpan currentSpan = transaction.CurrentSpan;

SetUserId

Associates a User Id with the current transaction.

This method requires .NET agent and .NET agent API version 10.9.0 or higher.

Syntax

ITransaction SetUserId(string userId)

Parameters

Example

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); 
ITransaction transaction = agent.CurrentTransaction; 
transaction.SetUserId("BobSmith123");