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 |
---|---|
Accepts incoming trace context headers from another service. | |
Adds trace context headers to an outgoing request. | |
Accepts an incoming distributed trace payload from another service. | |
Creates a distributed trace payload for inclusion in an outgoing request. | |
Add contextual information from your application to the current transaction in form of attributes. | |
Provides access to the currently executing span, which provides access to span-specific methods in the New Relic API. | |
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 |
---|---|
<T> | Required. Source of incoming Trace Context headers. |
Func<T, string, IEnumerable<string>> | Required. Caller-defined function to extract header data from the carrier. |
TransportType enum | Required. Describes the transport of the incoming payload (for example |
Usage considerations
- Distributed tracing must be enabled.
AcceptDistributedTraceHeaders
will be ignored ifInsertDistributedTraceHeaders
orAcceptDistributedTraceHeaders
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 |
---|---|
<T> | Required. Container where Trace Context headers are inserted.. |
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 |
---|---|
string | Required. A string representation of the incoming distributed trace payload. |
TransportType | Recommended. Describes the transport of the incoming payload (for example, Default |
Usage considerations
- Distributed tracing must be enabled.
- The payload can be a Base64-encoded or plain text string.
AcceptDistributedTracePayload
will be ignored ifCreateDistributedTracePayload
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
- Distributed tracing must be enabled.
CreateDistributedTracePayload
will be ignored ifAcceptDistributedTracePayload
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
Parameter | Description |
---|---|
string | Identifies the information being reported. Also known as the name.
|
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;
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 |
---|---|
string | The User Id to be associated with this transaction.
|
Example
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent(); ITransaction transaction = agent.CurrentTransaction; transaction.SetUserId("BobSmith123");