github.com/newrelic/go-agent@v3.26.0+incompatible/GETTING_STARTED.md (about)

     1  # Getting Started
     2  
     3  Follow these steps to instrument your application.  More information is
     4  available in the [GUIDE.md](GUIDE.md).
     5  
     6  ## Step 0: Installation
     7  
     8  The New Relic Go agent is a Go library. It has two dependencies on gRPC
     9  libraries - see [go.mod](v3/go.mod). Install the Go agent the same way you
    10  would install any other Go library. The simplest way is to run:
    11  
    12  ```
    13  go get github.com/newrelic/go-agent
    14  ```
    15  
    16  Then import the package in your application:
    17  ```go
    18  import "github.com/newrelic/go-agent/v3/newrelic"
    19  ```
    20  
    21  ## Step 1: Create an Application
    22  
    23  In your `main` function, or an `init` block, create an
    24  [Application](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#Application) using
    25   [ConfigOptions](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#ConfigOption).
    26   Available configurations are listed [here](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#Config).
    27  [Application](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#Application) is the
    28  starting point for all instrumentation.
    29  
    30  ```go
    31  func main() {
    32      // Create an Application:
    33      app, err := newrelic.NewApplication(
    34          // Name your application
    35          newrelic.ConfigAppName("Your Application Name"),
    36          // Fill in your New Relic license key
    37          newrelic.ConfigLicense("__YOUR_NEW_RELIC_LICENSE_KEY__"),
    38          // Add logging:
    39          newrelic.ConfigDebugLogger(os.Stdout),
    40          // Optional: add additional changes to your configuration via a config function:
    41          func(cfg *newrelic.Config) {
    42              cfg.CustomInsightsEvents.Enabled = false
    43          },
    44      )
    45      // If an application could not be created then err will reveal why.
    46      if err != nil {
    47          fmt.Println("unable to create New Relic Application", err)
    48      }
    49      // Now use the app to instrument everything!
    50  }
    51  ```
    52  
    53  Now start your application, and within minutes it will appear in the New Relic
    54  UI.  Your application in New Relic won't contain much data (until we complete
    55  the steps below!), but you will already be able to see a
    56  [Go runtime](https://docs.newrelic.com/docs/agents/go-agent/features/go-runtime-page-troubleshoot-performance-problems)
    57  page that shows goroutine counts, garbage collection, memory, and CPU usage.
    58  
    59  ## Step 2: Instrument Requests Using Transactions
    60  
    61  [Transactions](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#Transaction) are
    62  used to time inbound requests and background tasks.  Use them to see your
    63  application's throughput and response time.  The instrumentation strategy
    64  depends on the framework you're using:
    65  
    66  #### Standard HTTP Library
    67  
    68  If you are using the standard library `http` package, use
    69  [WrapHandle](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#WrapHandle) and
    70  [WrapHandleFunc](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#WrapHandleFunc).
    71  As an example, the following code:
    72  
    73  ```go
    74  http.HandleFunc("/users", usersHandler)
    75  ```
    76  Can be instrumented like this:
    77  ```go
    78  http.HandleFunc(newrelic.WrapHandleFunc(app, "/users", usersHandler))
    79  ```
    80  
    81  [Full Example Application](./v3/examples/server/main.go)
    82  
    83  #### Popular Web Framework
    84  
    85  If you are using a popular framework, then there may be an integration package
    86  designed to instrument it.  [List of New Relic Go agent integration packages](./README.md#integrations).
    87  
    88  #### Manual Transactions
    89  
    90  If you aren't using the `http` standard library package or an
    91  integration package supported framework, you can create transactions
    92  directly using the application's `StartTransaction` method:
    93  
    94  ```go
    95  func myHandler(rw http.ResponseWriter, req *http.Request) {
    96      txn := h.App.StartTransaction("myHandler")
    97      defer txn.End()
    98      // Setting the response writer and request is optional. If you don't
    99      // set the request, the transaction is considered a background task.
   100      txn.SetWebRequestHTTP(req)
   101      // Use the ResponseWriter returned in place of the previous ResponseWriter
   102      rw = txn.SetWebResponse(rw)
   103      rw.Write(data)
   104  }
   105  ```
   106  
   107  Be sure to use a limited set of unique names to ensure that transactions are
   108  grouped usefully.  Don't use dynamic URLs!
   109  
   110  [More information about transactions](GUIDE.md#transactions)
   111  
   112  ## Step 3: Instrument Segments
   113  
   114  Segments show you where the time in your transactions is being spent.  There are
   115  four types of segments:
   116  [Segment](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#Segment),
   117  [ExternalSegment](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#ExternalSegment),
   118  [DatastoreSegment](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#DatastoreSegment),
   119  and
   120  [MessageProducerSegment](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#MessageProducerSegment).
   121  
   122  Creating a segment requires access to the transaction.  You can pass the
   123  transaction around your functions inside
   124  a [context.Context](https://golang.org/pkg/context/#Context) (preferred), or as an explicit transaction
   125  parameter of the function.  Functions
   126  [FromContext](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#FromContext)
   127  and [NewContext](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#NewContext) make it
   128  easy to store and retrieve the transaction from a context.
   129  
   130  You may not even need to add the transaction to the context:
   131  [WrapHandle](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#WrapHandle) and
   132  [WrapHandleFunc](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic/#WrapHandleFunc)
   133  add the transaction to the request's context automatically.
   134  
   135  ```go
   136  func instrumentMe(ctx context.Context) {
   137      txn := newrelic.FromContext(ctx)
   138      segment := txn.StartSegment("instrumentMe")
   139      time.Sleep(1 * time.Second)
   140      segment.End()
   141  }
   142  
   143  func myHandler(w http.ResponseWriter, r *http.Request) {
   144      instrumentMe(r.Context())
   145  }
   146  
   147  func main() {
   148      app, _ := newrelic.NewApplication(
   149          newrelic.ConfigAppName("appName"),
   150          newrelic.ConfigLicense("__license__"),
   151      )
   152      http.HandleFunc(newrelic.WrapHandleFunc(app, "/handler", myHandler))
   153  }
   154  ```
   155  
   156  [More information about segments](GUIDE.md#segments)
   157  
   158  ## Extra Credit
   159  
   160  Read our [GUIDE.md](GUIDE.md) and the
   161  [godocs](https://godoc.org/github.com/newrelic/go-agent/v3/newrelic) to learn more about
   162  what else you can do with the Go Agent.