// Copyright 2020 New Relic Corporation. All rights reserved. // SPDX-License-Identifier: Apache-2.0 package newrelic import ( "net/http" "net/url" ) // Transaction instruments one logical unit of work: either an inbound web // request or background task. Start a new Transaction with the // Application.StartTransaction() method. type Transaction interface { // The transaction's http.ResponseWriter methods delegate to the // http.ResponseWriter provided as a parameter to // Application.StartTransaction or Transaction.SetWebResponse. This // allows instrumentation of the response code and response headers. // These methods may be called safely if the transaction does not have a // http.ResponseWriter. http.ResponseWriter // End finishes the Transaction. After that, subsequent calls to End or // other Transaction methods have no effect. All segments and // instrumentation must be completed before End is called. End() error // Ignore prevents this transaction's data from being recorded. Ignore() error // SetName names the transaction. Use a limited set of unique names to // ensure that Transactions are grouped usefully. SetName(name string) error // NoticeError records an error. The Transaction saves the first five // errors. For more control over the recorded error fields, see the // newrelic.Error type. In certain situations, using this method may // result in an error being recorded twice: Errors are automatically // recorded when Transaction.WriteHeader receives a status code above // 400 or below 100 that is not in the IgnoreStatusCodes configuration // list. This method is unaffected by the IgnoreStatusCodes // configuration list. NoticeError(err error) error // AddAttribute adds a key value pair to the transaction event, errors, // and traces. // // The key must contain fewer than than 255 bytes. The value must be a // number, string, or boolean. // // For more information, see: // https://docs.newrelic.com/docs/agents/manage-apm-agents/agent-metrics/collect-custom-attributes AddAttribute(key string, value interface{}) error // SetWebRequest marks the transaction as a web transaction. If // WebRequest is non-nil, SetWebRequest will additionally collect // details on request attributes, url, and method. If headers are // present, the agent will look for a distributed tracing header. Use // NewWebRequest to transform a *http.Request into a WebRequest. SetWebRequest(WebRequest) error // SetWebResponse sets transaction's http.ResponseWriter. After calling // this method, the transaction may be used in place of the // ResponseWriter to intercept the response code. This method is useful // when the ResponseWriter is not available at the beginning of the // transaction (if so, it can be given as a parameter to // Application.StartTransaction). This method will return a reference // to the transaction which implements the combination of // http.CloseNotifier, http.Flusher, http.Hijacker, and io.ReaderFrom // implemented by the ResponseWriter. SetWebResponse(http.ResponseWriter) Transaction // StartSegmentNow starts timing a segment. The SegmentStartTime // returned can be used as the StartTime field in Segment, // DatastoreSegment, or ExternalSegment. We recommend using the // StartSegmentNow function instead of this method since it checks if // the Transaction is nil. StartSegmentNow() SegmentStartTime // CreateDistributedTracePayload creates a payload used to link // transactions. CreateDistributedTracePayload should be called every // time an outbound call is made since the payload contains a timestamp. // // StartExternalSegment calls CreateDistributedTracePayload, so you // don't need to use it for outbound HTTP calls: Just use // StartExternalSegment! // // This method never returns nil. If the application is disabled or not // yet connected then this method returns a shim implementation whose // methods return empty strings. CreateDistributedTracePayload() DistributedTracePayload // AcceptDistributedTracePayload links transactions by accepting a // distributed trace payload from another transaction. // // Application.StartTransaction calls this method automatically if a // payload is present in the request headers. Therefore, this method // does not need to be used for typical HTTP transactions. // // AcceptDistributedTracePayload should be used as early in the // transaction as possible. It may not be called after a call to // CreateDistributedTracePayload. // // The payload parameter may be a DistributedTracePayload, a string, or // a []byte. AcceptDistributedTracePayload(t TransportType, payload interface{}) error // Application returns the Application which started the transaction. Application() Application // BrowserTimingHeader generates the JavaScript required to enable New // Relic's Browser product. This code should be placed into your pages // as close to the top of the element as possible, but after any // position-sensitive tags (for example, X-UA-Compatible or // charset information). // // This function freezes the transaction name: any calls to SetName() // after BrowserTimingHeader() will be ignored. // // The *BrowserTimingHeader return value will be nil if browser // monitoring is disabled, the application is not connected, or an error // occurred. It is safe to call the pointer's methods if it is nil. BrowserTimingHeader() (*BrowserTimingHeader, error) // NewGoroutine allows you to use the Transaction in multiple // goroutines. // // Each goroutine must have its own Transaction reference returned by // NewGoroutine. You must call NewGoroutine to get a new Transaction // reference every time you wish to pass the Transaction to another // goroutine. It does not matter if you call this before or after the // other goroutine has started. // // All Transaction methods can be used in any Transaction reference. // The Transaction will end when End() is called in any goroutine. // // Example passing a new Transaction reference directly to another // goroutine: // // go func(txn newrelic.Transaction) { // defer newrelic.StartSegment(txn, "async").End() // time.Sleep(100 * time.Millisecond) // }(txn.NewGoroutine()) // // Example passing a new Transaction reference on a channel to another // goroutine: // // ch := make(chan newrelic.Transaction) // go func() { // txn := <-ch // defer newrelic.StartSegment(txn, "async").End() // time.Sleep(100 * time.Millisecond) // }() // ch <- txn.NewGoroutine() // NewGoroutine() Transaction // GetTraceMetadata returns distributed tracing identifiers. Empty // string identifiers are returned if the transaction has finished. GetTraceMetadata() TraceMetadata // GetLinkingMetadata returns the fields needed to link data to a trace or // entity. GetLinkingMetadata() LinkingMetadata // IsSampled indicates if the Transaction is sampled. A sampled // Transaction records a span event for each segment. Distributed tracing // must be enabled for transactions to be sampled. False is returned if // the transaction has finished. IsSampled() bool } // DistributedTracePayload traces requests between applications or processes. // DistributedTracePayloads are automatically added to HTTP requests by // StartExternalSegment, so you only need to use this if you are tracing through // a message queue or another non-HTTP communication library. The // DistributedTracePayload may be marshalled in one of two formats: HTTPSafe or // Text. All New Relic agents can accept payloads in either format. type DistributedTracePayload interface { // HTTPSafe serializes the payload into a string containing http safe // characters. HTTPSafe() string // Text serializes the payload into a string. The format is slightly // more compact than HTTPSafe. Text() string } const ( // DistributedTracePayloadHeader is the header used by New Relic agents // for automatic trace payload instrumentation. DistributedTracePayloadHeader = "Newrelic" ) // TransportType is used in Transaction.AcceptDistributedTracePayload() to // represent the type of connection that the trace payload was transported over. type TransportType struct{ name string } // TransportType names used across New Relic agents: var ( TransportUnknown = TransportType{name: "Unknown"} TransportHTTP = TransportType{name: "HTTP"} TransportHTTPS = TransportType{name: "HTTPS"} TransportKafka = TransportType{name: "Kafka"} TransportJMS = TransportType{name: "JMS"} TransportIronMQ = TransportType{name: "IronMQ"} TransportAMQP = TransportType{name: "AMQP"} TransportQueue = TransportType{name: "Queue"} TransportOther = TransportType{name: "Other"} ) // WebRequest may be implemented to provide request information to // Transaction.SetWebRequest. type WebRequest interface { // Header may return nil if you don't have any headers or don't want to // transform them to http.Header format. Header() http.Header // URL may return nil if you don't have a URL or don't want to transform // it to *url.URL. URL() *url.URL Method() string // If a distributed tracing header is found in the headers returned by // Header(), this TransportType will be used in the distributed tracing // metrics. Transport() TransportType } // NewWebRequest turns a *http.Request into a WebRequest for input into // Transaction.SetWebRequest. func NewWebRequest(request *http.Request) WebRequest { if nil == request { return nil } return requestWrap{request: request} } // NewStaticWebRequest takes the minimum necessary information and creates a static WebRequest out of it func NewStaticWebRequest(hdrs http.Header, url *url.URL, method string, transport TransportType) WebRequest { return staticWebRequest{hdrs, url, method, transport} } // LinkingMetadata is returned by Transaction.GetLinkingMetadata. It contains // identifiers needed link data to a trace or entity. type LinkingMetadata struct { // TraceID identifies the entire distributed trace. This field is empty // if distributed tracing is disabled. TraceID string // SpanID identifies the currently active segment. This field is empty // if distributed tracing is disabled or the transaction is not sampled. SpanID string // EntityName is the Application name as set on the newrelic.Config. If // multiple application names are specified, only the first is returned. EntityName string // EntityType is the type of this entity and is always the string // "SERVICE". EntityType string // EntityGUID is the unique identifier for this entity. EntityGUID string // Hostname is the hostname this entity is running on. Hostname string } // TraceMetadata is returned by Transaction.GetTraceMetadata. It contains // distributed tracing identifiers. type TraceMetadata struct { // TraceID identifies the entire distributed trace. This field is empty // if distributed tracing is disabled. TraceID string // SpanID identifies the currently active segment. This field is empty // if distributed tracing is disabled or the transaction is not sampled. SpanID string }