github.com/newrelic/go-agent@v3.26.0+incompatible/_integrations/nrnats/nrnats_doc.go (about)

     1  // Copyright 2020 New Relic Corporation. All rights reserved.
     2  // SPDX-License-Identifier: Apache-2.0
     3  
     4  // Package nrnats instruments https://github.com/nats-io/nats.go.
     5  //
     6  // This package can be used to simplify instrumenting NATS publishers and subscribers. Currently due to the nature of
     7  // the NATS framework we are limited to two integration points: `StartPublishSegment` for publishers, and `SubWrapper`
     8  // for subscribers.
     9  //
    10  // NATS publishers
    11  //
    12  // To generate an external segment for any method that publishes or responds to a NATS message, use the
    13  // `StartPublishSegment` method. The resulting segment will also need to be ended. Example:
    14  //
    15  //	nc, _ := nats.Connect(nats.DefaultURL)
    16  //	txn := currentTransaction()  // current newrelic.Transaction
    17  //	subject := "testing.subject"
    18  //	seg := nrnats.StartPublishSegment(txn, nc, subject)
    19  //	err := nc.Publish(subject, []byte("Hello World"))
    20  //	if nil != err {
    21  //		panic(err)
    22  //	}
    23  //	seg.End()
    24  //
    25  // Or:
    26  //
    27  //	nc, _ := nats.Connect(nats.DefaultURL)
    28  //	txn := currentTransaction()  // current newrelic.Transaction
    29  //	subject := "testing.subject"
    30  //	defer nrnats.StartPublishSegment(txn, nc, subject).End()
    31  //	nc.Publish(subject, []byte("Hello World"))
    32  //
    33  //
    34  // NATS subscribers
    35  //
    36  // The `nrnats.SubWrapper` function can be used to wrap the function for `nats.Subscribe`
    37  // (https://godoc.org/github.com/nats-io/go-nats#Conn.Subscribe or
    38  // https://godoc.org/github.com/nats-io/go-nats#EncodedConn.Subscribe)
    39  // and `nats.QueueSubscribe` (https://godoc.org/github.com/nats-io/go-nats#Conn.QueueSubscribe or
    40  // https://godoc.org/github.com/nats-io/go-nats#EncodedConn.QueueSubscribe)
    41  // If the `newrelic.Application` parameter is non-nil, it will create a `newrelic.Transaction` and end the transaction
    42  // when the passed function is complete.  Example:
    43  //
    44  //	nc, _ := nats.Connect(nats.DefaultURL)
    45  //	app := createNRApp()  // newrelic.Application
    46  //	subject := "testing.subject"
    47  //	nc.Subscribe(subject, nrnats.SubWrapper(app, myMessageHandler))
    48  //
    49  // Full Publisher/Subscriber example:
    50  // https://github.com/newrelic/go-agent/blob/master/_integrations/nrnats/examples/main.go
    51  package nrnats
    52  
    53  import "github.com/newrelic/go-agent/internal"
    54  
    55  func init() { internal.TrackUsage("integration", "framework", "nats") }