Go agent logs in context

For most users, using the automatic log forwarding built into the Go agent is the best solution. It's easy to set up and works great for a majority of use cases. Learn about log forwarding limitations.

Automatic application log forwarding is now enabled by default in Go agent version 3.20.0 or higher. If your applications use these Go agent versions, you don't need to change your config options to enable automatic log forwarding.

If you're using an older version of the Go agent, you'll need to modify its config to enable application log forwarding:

app, err := newrelic.NewApplication(
  newrelic.ConfigAppLogForwardingEnabled(true),
)

For users with more custom logging needs, or users who want to send more than 10,000 logs per 60 second cycle, or 833 logs per 5 second cycle, to New Relic we recommend that you manually set up log forwarding. Once you have a log forwarder configured to send logs to New Relic, allow the Go agent to enrich your logs for forwarding by modifying its config to include this setting:

app, err := newrelic.NewApplication(
  newrelic.ConfigAppLogDecoratingEnabled(true),
)

If you are using versions v3.20.0+ of the Go agent, you need to disable application log forwarding in order to avoid duplicating the logs collected by New Relic.

app, err := newrelic.NewApplication(
  newrelic.ConfigAppLogDecoratingEnabled(true),
  newrelic.ConfigAppLogForwardingEnabled(false),
)

The logWriter library is an io.Writer that automatically integrates the latest New Relic Logs in Context features into the go standard library logger. Follow these steps to install it in your application. This library requires the installed version of the Go agent to be 3.19.1 or higher.

1. Add the logWriter package to your module.

$
go get github.com/newrelic/go-agent/v3/integrations/logcontext-v2/logWriter

2. Import the logWriter package in the file where you initialize your logger.

import (
  "log"

  "github.com/newrelic/go-agent/v3/integrations/logcontext-v2/logWriter"
)

3. Create a logWriter object. It must be passed a valid io.Writer, which is where logs will be written to, and an initialized go-agent application. The following example writes to standard out.

writer := logWriter.New(os.Stdout, newRelicApp)

4. Create a logger object with your new logWriter object as the logger's output destination.

logger := log.New(&writer, "", log.Default().Flags())

At this point, any log written with the logger created will be handled by the go-agent based on your logging config settings.

Transactions

If you want to capture the context of a transaction, a new logWriter object and logger object must be created. To create a new logWriter object for your transaction use either the WithTransaction() or WithContext() functions depending on how the transaction is passed to your function. These functions will make a new copy of the original logWriter object with the transaction context included.

If your function receives a context wrapped with a transaction, use the WithContext() function:

txnWriter := writer.WithContext(myWrappedContext)

If your function receives a transaction pointer, then use the WithTransaction() function:

txnWriter := writer.WithTransaction(myTransaction)

Make sure to always create a new logger with a new logWriter for each transaction. This prevents the possibility of asynchronous processes accessing the same logger object with different contextual information.

txnLogger := log.New(txnWriter, "", log.Default().Flags())

Troubleshooting

The logWriter tool is designed to fail silently. To enable debugging information, call the DebugLogging(true) method on your logWriter object. When an error occurs in in the logWriter, it will always print your unedited log line on the first line. When DebugLogging is enabled, it will print an error message on the following line if an error occurs.

writer.DebugLogging(true)

The zerologWriter library is an io.Writer that automatically integrates the latest New Relic Logs in Context features into zerolog. Follow these steps to install it in your application. This library requires the installed version of the go-agent to be 3.19.1 or higher.

1. Add the zerologWriter package to your module.

$
go get github.com/newrelic/go-agent/v3/integrations/logcontext-v2/zerologWriter

2. Import the zerologWriter package in the file where you initialize your zerolog logger.

import (
  "log"

  "github.com/newrelic/go-agent/v3/integrations/logcontext-v2/zerologWriter"
)

3. Create a zerologWriter object. It must be passed a valid io.Writer, which is where logs will be written to, and an initialized go-agent application. The following example writes to standard out.

writer := logWriter.New(os.Stdout, newRelicApp)

4. Create a logger object with your new zerologWriter object as the logger's output destination.

logger := zerolog.New(writer)

At this point, any log written with the logger created will be handled by the go-agent based on your logging config settings.

Transactions

If you want to capture the context of a transaction, a new zerologWriter object and logger object must be created. To create a new zerologWriter object for your transaction use either the WithTransaction() or WithContext() functions depending on how the transaction is passed to your function. These functions will make a new copy of the original zerologWriter object with the transaction context included.

If your function receives a context wrapped with a transaction, use the WithContext() function:

txnWriter := writer.WithContext(myWrappedContext)

If your function receives a transaction pointer, then use the WithTransaction() function:

txnWriter := writer.WithTransaction(myTransaction)

Make sure to always create a new logger with a new zerologWriter for each transaction. This prevents the possibility of asynchronous processes accessing the same logger object with different contextual information.

txnLogger := logger.Output(txnWriter)

Troubleshooting

The zerologWriter tool is designed to fail silently. To enable debugging information, call the DebugLogging(true) method on your zerologWriter object. When an error occurs in in the zerologWriter, it will always print your unedited log line on the first line. When DebugLogging is enabled, it will print an error message on the following line if an error occurs.

writer.DebugLogging(true)

The nrlogrus plugin enables automatic logs in context ingestion with the logrus logging framework. Once your application is configured to use it, the go-agent will automatically ingest any logs written in logrus. This requires the installed go-agent version to be 3.18.0 or higher.

1. Add the nrlogrus package to your module.

$
go get github.com/newrelic/go-agent/v3/integrations/logcontext-v2/nrlogrus

2. Import the nrlogrus package in the file where you initialize your logrus logger.

import (
  "github.com/newrelic/go-agent/v3/integrations/logcontext-v2/nrlogrus"

  "github.com/sirupsen/logrus"
)

3. Configure and create a new nrlogrus formatter. It must be passed a valid application, and any valid logrus formatter. The formatter passed will determine the appearance of the logs that get written.

nrlogrusFormatter := nrlogrus.NewFormatter(newRelicApplication, &logrus.TextFormatter{})

4. Set your logger's formatter to the newly create nrlogrus formatter.

log := logrus.New()
log.SetFormatter(nrlogrusFormatter)

At this point, any log written with the logger created will be handled by the go-agent based on your logging config settings.

Transactions

When instrumenting logs inside of a transaction, you must pass that transaction to logrus as a context. This will create a new logger object for that transaction that links logs handled by the agent to the transaction and spans they occured in.

If you have a context that contains a transaction:

txnLogger := log.WithContext(yourWrappedContext)

Otherwise, you can create a context and pass it to logrus:

txnLogger := log.WithContext(newrelic.NewContext(context.Background(), txn))