• English日本語한국어
  • Log inStart now

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:

Name

Description

AcceptDistributedTraceHeaders

Accepts incoming trace context headers from another service.

InsertDistributedTraceHeaders

Adds trace context headers to an outgoing request.

AcceptDistributedTracePayload (obsolete)

Accepts an incoming distributed trace payload from another service.

CreateDistributedTracePayload (obsolete)

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.

SetUserId

Associates a User Id to the current transaction.

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

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 (for example 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 = 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

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

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

Caution

This API is not available in the .NET agent v9.0 or higher. Please use AcceptDistributedTraceHeaders instead.

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 (for example, 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 (obsolete)

Caution

This API is not available in the .NET agent v9.0 or higher. Please use InsertDistributedTraceHeaders instead.

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.

Note: null values will not be recorded.

.NET type

How the value will be represented

byte, Int16, Int32, Int64

sbyte, UInt16, UInt32, UInt64

As an integral value.

float, double, decimal

A decimal-based number.

string

A string truncated after 255-bytes.

Empty strings are supported.

bool

True or false.

DateTime

A string representation following the ISO-8601 format, including time zone information:

Example: 2020-02-13T11:31:19.5767650-08:00

TimeSpan

A decimal-based number representing number of seconds.

everything else

The ToString() method will be applied. Custom types must have an implementation of Object.ToString() or they will throw an exception.

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

Parameter

Description

userId

string

The User Id to be associated with this transaction.

  • null, empty and whitespace values will be ignored.

Example

IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
transaction.SetUserId("BobSmith123");
Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.