ITransaction

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.

This section contains descriptions and parameters of three ITransaction methods:

Name Description
AcceptDistributedTraceHeaders Accepts incoming trace context headers from another service.
InsertDistributedTraceHeaders Adds trace context headers to an outgoing request.
AcceptDistributedTracePayload (deprecated) Accepts an incoming distributed trace payload from another service.
CreateDistributedTracePayload (deprecated) Creates a distributed trace payload for inclusion in an outgoing request.
AddCustomAttribute Add contextual information from your application to the current transaction in form of attributes.
CurrentSpan Provides access to the currently executing span, which provides access to span-specific methods in the New Relic API.

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 AcceptDistributedHeaders(carrier, getter, transportType)

Parameters

Name Description
carrier
<T>
Required. Source of incoming Trace Context headers.
getter
Func<T, string, IEnumerable<string>>

Required. Caller-defined function to extract header data from the carrier.

transportType
TransportType enum

Required. Describes the transport of the incoming payload (e.g. TransportType.HTTP).

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 = 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

Name Description
carrier
<T>
Required. Container where Trace Context headers are inserted..
setter
Action<T, string, string>
Required. Caller-defined Action to insert header data into the carrier.

Usage considerations

Example

HttpRequestMessage requestMessage = new HttpRequestMessage(HttpMethod.Get, "https://remote-address");
IAgent agent = GetAgent();
ITransaction currentTransaction = _agent.CurrentTransaction;

var setter = new Action<System.Net.HttpWebRequest, string, string>((carrier, key, value) =>
  {
    carrier.Headers?.Set(key, value);
  });

currentTransaction.InsertDistributedTraceHeaders(requestMessage, setter);

AcceptDistributedTracePayload (deprecated)

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

Name Description
payload
string
Required. A string representation of the incoming distributed trace payload.
transportType
TransportType
enum

Recommended. Describes the transport of the incoming payload (e.g. http).

Default TransportType.Unknown.

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 (deprecated)

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

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

Parameter Description
key
string

Identifies the information being reported. Also known as the name.

  • Empty keys are not supported.
  • Keys are limited to 255-bytes. Attributes with keys larger than 255-bytes will be ignored.
value
object
The value being reported.

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;

Example(s)

For more help

Recommendations for learning more: