nrmicro

README

_integrations/nrmicro

Package nrmicro instruments https://github.com/micro/go-micro.

import "github.com/newrelic/go-agent/_integrations/nrmicro"

For more information, see godocs.

Documentation

Overview

Package nrmicro instruments https://github.com/micro/go-micro.

This package can be used to instrument Micro Servers, Clients, Producers, and Subscribers.

Micro Servers

To instrument a Micro Server, use the `micro.WrapHandler` (https://godoc.org/github.com/micro/go-micro#WrapHandler) option with `nrmicro.HandlerWrapper` and your `newrelic.Application` and pass it to the `micro.NewService` method. Example:

cfg := newrelic.NewConfig("Micro Server", os.Getenv("NEW_RELIC_LICENSE_KEY"))
app, _ := newrelic.NewApplication(cfg)
service := micro.NewService(
	micro.WrapHandler(nrmicro.HandlerWrapper(app)),
)

Alternatively, use the `server.WrapHandler` (https://godoc.org/github.com/micro/go-micro/server#WrapHandler) option with `nrmicro.HandlerWrapper` and your `newrelic.Application` and pass it to the `server.NewServer` method. Example:

cfg := newrelic.NewConfig("Micro Server", os.Getenv("NEW_RELIC_LICENSE_KEY"))
app, _ := newrelic.NewApplication(cfg)
svr := server.NewServer(
	server.WrapHandler(nrmicro.HandlerWrapper(app)),
)

If more than one wrapper is passed to `micro.WrapHandler` or `server.WrapHandler` as a list, be sure that the `nrmicro.HandlerWrapper` is first in this list.

This wrapper creates transactions for inbound calls. The transaction is added to the call context and can be accessed in your method handlers using `newrelic.FromContext` (https://godoc.org/github.com/newrelic/go-agent#FromContext).

When an error is returned and it is of type Micro `errors.Error` (https://godoc.org/github.com/micro/go-micro/errors#Error), the error that is recorded is based on the HTTP response code (found in the Code field). Values above 400 or below 100 that are not in the IgnoreStatusCodes (https://godoc.org/github.com/newrelic/go-agent#Config) configuration list are recorded as errors. A 500 response code and corresponding error is recorded when the error is of any other type. A 200 response code is recorded if no error is returned.

Full server example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrmicro/example/server/server.go

Micro Clients

There are three different ways to instrument a Micro Client and create External segments for `Call`, `Publish`, and `Stream` methods.

No matter which way the Micro `client.Client` is wrapped, all calls to `Client.Call`, `Client.Publish`, or `Client.Stream` must be done with a context which contains a `newrelic.Transaction`.

ctx = newrelic.NewContext(ctx, txn)
err := cli.Call(ctx, req, &rsp)

1. The first option is to wrap the `Call`, `Publish`, and `Stream` methods on a client using the `micro.WrapClient` (https://godoc.org/github.com/micro/go-micro#WrapClient) option with `nrmicro.ClientWrapper` and pass it to the `micro.NewService` method. If more than one wrapper is passed to `micro.WrapClient`, ensure that the `nrmicro.ClientWrapper` is the first in the list. `ExternalSegment`s will be created each time a `Call` or `Stream` method is called on the client. `MessageProducerSegment`s will be created each time a `Publish` method is called on the client. Example:

service := micro.NewService(
	micro.WrapClient(nrmicro.ClientWrapper()),
)
cli := service.Client()

It is also possible to use the `client.Wrap` (https://godoc.org/github.com/micro/go-micro/client#Wrap) option with `nrmicro.ClientWrapper` and pass it to the `client.NewClient` method to achieve the same result.

cli := client.NewClient(
	client.Wrap(nrmicro.ClientWrapper()),
)

2. The second option is to wrap just the `Call` method on a client using the `micro.WrapCall` (https://godoc.org/github.com/micro/go-micro#WrapCall) option with `nrmicro.CallWrapper` and pass it to the `micro.NewService` method. If more than one wrapper is passed to `micro.WrapCall`, ensure that the `nrmicro.CallWrapper` is the first in the list. External segments will be created each time a `Call` method is called on the client. Example:

service := micro.NewService(
	micro.WrapCall(nrmicro.CallWrapper()),
)
cli := service.Client()

It is also possible to use the `client.WrapCall` (https://godoc.org/github.com/micro/go-micro/client#WrapCall) option with `nrmicro.CallWrapper` and pass it to the `client.NewClient` method to achieve the same result.

cli := client.NewClient(
	client.WrapCall(nrmicro.CallWrapper()),
)

3. The third option is to wrap the Micro Client directly using `nrmicro.ClientWrapper`. `ExternalSegment`s will be created each time a `Call` or `Stream` method is called on the client. `MessageProducerSegment`s will be created each time a `Publish` method is called on the client. Example:

cli := client.NewClient()
cli = nrmicro.ClientWrapper()(cli)

Full client example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrmicro/example/client/client.go

Micro Producers

To instrument a Micro Producer, wrap the Micro Client using the `nrmico.ClientWrapper` as described in option 1 or 3 above. `MessageProducerSegment`s will be created each time a `Publish` method is called on the client. Be sure the context passed to the `Publish` method contains a `newrelic.Transaction`.

service := micro.NewService(
	micro.WrapClient(nrmicro.ClientWrapper()),
)
cli := service.Client()

// Add the transaction to the context
ctx := newrelic.NewContext(context.Background(), txn)
msg := cli.NewMessage("my.example.topic", "hello world")
err := cli.Publish(ctx, msg)

Full Publisher/Subscriber example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrmicro/example/pubsub/main.go

Micro Subscribers

To instrument a Micro Subscriber use the `micro.WrapSubscriber` (https://godoc.org/github.com/micro/go-micro#WrapSubscriber) option with `nrmicro.SubscriberWrapper` and your `newrelic.Application` and pass it to the `micro.NewService` method. Example:

cfg := newrelic.NewConfig("Micro Subscriber", os.Getenv("NEW_RELIC_LICENSE_KEY"))
app, _ := newrelic.NewApplication(cfg)
service := micro.NewService(
	micro.WrapSubscriber(nrmicro.SubscriberWrapper(app)),
)

Alternatively, use the `server.WrapSubscriber` (https://godoc.org/github.com/micro/go-micro/server#WrapSubscriber) option with `nrmicro.SubscriberWrapper` and your `newrelic.Application` and pass it to the `server.NewServer` method. Example:

cfg := newrelic.NewConfig("Micro Subscriber", os.Getenv("NEW_RELIC_LICENSE_KEY"))
app, _ := newrelic.NewApplication(cfg)
svr := server.NewServer(
	server.WrapSubscriber(nrmicro.SubscriberWrapper(app)),
)

If more than one wrapper is passed to `micro.WrapSubscriber` or `server.WrapSubscriber` as a list, be sure that the `nrmicro.SubscriberWrapper` is first in this list.

This wrapper creates background transactions for inbound calls. The transaction is added to the subscriber context and can be accessed in your subscriber handlers using `newrelic.FromContext`.

If a Subscriber returns an error, it will be recorded and reported.

Full Publisher/Subscriber example: https://github.com/newrelic/go-agent/blob/master/_integrations/nrmicro/example/pubsub/main.go

Index

• func CallWrapper() client.CallWrapper
• func ClientWrapper() client.Wrapper
• func HandlerWrapper(app newrelic.Application) server.HandlerWrapper
• func SubscriberWrapper(app newrelic.Application) server.SubscriberWrapper

Functions

func CallWrapper

func CallWrapper() client.CallWrapper

CallWrapper wraps the `Call` method of a Micro `client.Client` (https://godoc.org/github.com/micro/go-micro/client#Client) instance. External segments will be created for each call to the client's `Call` method. The `newrelic.Transaction` must be put into the context using `newrelic.NewContext` (https://godoc.org/github.com/newrelic/go-agent#NewContext) when calling `Call`.

func ClientWrapper

func ClientWrapper() client.Wrapper

ClientWrapper wraps a Micro `client.Client` (https://godoc.org/github.com/micro/go-micro/client#Client) instance. External segments will be created for each call to the client's `Call`, `Publish`, or `Stream` methods. The `newrelic.Transaction` must be put into the context using `newrelic.NewContext` (https://godoc.org/github.com/newrelic/go-agent#NewContext) when calling one of those methods.

func HandlerWrapper

func HandlerWrapper(app newrelic.Application) server.HandlerWrapper

HandlerWrapper wraps a Micro `server.Server` (https://godoc.org/github.com/micro/go-micro/server#Server) handler.

This wrapper creates transactions for inbound calls. The transaction is added to the call context and can be accessed in your method handlers using `newrelic.FromContext` (https://godoc.org/github.com/newrelic/go-agent#FromContext).

When an error is returned and it is of type Micro `errors.Error` (https://godoc.org/github.com/micro/go-micro/errors#Error), the error that is recorded is based on the HTTP response code (found in the Code field). Values above 400 or below 100 that are not in the IgnoreStatusCodes (https://godoc.org/github.com/newrelic/go-agent#Config) configuration list are recorded as errors. A 500 response code and corresponding error is recorded when the error is of any other type. A 200 response code is recorded if no error is returned.

func SubscriberWrapper

func SubscriberWrapper(app newrelic.Application) server.SubscriberWrapper

SubscriberWrapper wraps a Micro `server.Subscriber` (https://godoc.org/github.com/micro/go-micro/server#Subscriber) instance.

This wrapper creates background transactions for inbound calls. The transaction is added to the subscriber context and can be accessed in your subscriber handlers using `newrelic.FromContext` (https://godoc.org/github.com/newrelic/go-agent#FromContext).

The attribute `"message.routingKey"` is added to the transaction and will appear on transaction events, transaction traces, error events, and error traces. It corresponds to the `server.Message`'s Topic (https://godoc.org/github.com/micro/go-micro/server#Message).

If a Subscriber returns an error, it will be recorded and reported.