instamongo

README

Instana instrumentation for MongoDB driver

This module contains instrumentation code for MongoDB clients written with go.mongodb.org/mongo-driver.

Installation

To add the module to your go.mod file run the following command in your project directory:

$ go get github.com/instana/go-sensor/instrumentation/instamongo

Usage

instamongo offers function wrappers for mongo.Connect() and mongo.NewClient() that initialize and instrument an instance of mongo.Client by adding a command monitor to its configuration. This monitor then use provided instana.Sensor to trace MongoDB queries made with this client instance:

client, err := instamongo.Connect(
	context.Background(),
	sensor, // an instance of instana.Sensor used to instrument your application
	options.Client().ApplyURI("mongodb://localhost:27017"),
)

Any existing options.CommandMonitor provided with client options will be preserved and called for each command event.

See the instamongo package documentation for detailed examples.

Documentation

Overview

Example

The following example demonstrates how to instrument a MongoDB client with instana using github.com/instana/go-sensor/instrumentation/instamongo wrapper module.

// (c) Copyright IBM Corp. 2021
// (c) Copyright Instana Inc. 2021

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	instana "github.com/instana/go-sensor"
	"github.com/instana/go-sensor/instrumentation/instamongo"
	"go.mongodb.org/mongo-driver/bson"
	"go.mongodb.org/mongo-driver/mongo/options"
)

const localhostMongo = "mongodb://localhost:27017"

// The following example demonstrates how to instrument a MongoDB client with instana using
// github.com/instana/go-sensor/instrumentation/instamongo wrapper module.
func main() {
	// Initialize Instana sensor
	sensor := instana.NewSensor("mongo-client")

	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	// Use instamongo.Connect() to establish connection to MongoDB and instrument the client
	client, err := instamongo.Connect(ctx, sensor, options.Client().ApplyURI(localhostMongo))
	if err != nil {
		log.Fatalf("failed to connect to %s: %s", localhostMongo, err)
	}

	// Use instrumented client as usual
	dbs, err := client.ListDatabases(context.Background(), bson.D{})
	if err != nil {
		log.Fatalf("failed to list databases: %s", err)
	}

	fmt.Println("found", len(dbs.Databases), "database(s)")
	for _, db := range dbs.Databases {
		fmt.Println("* ", db.Name)
	}
}

Index

• Constants
• func Connect(ctx context.Context, sensor instana.TracerLogger, ...) (*mongo.Client, error)
• func NewClient(sensor instana.TracerLogger, opts ...*options.ClientOptions) (*mongo.Client, error)
• func NewCommandMonitor(sensor instana.TracerLogger) *event.CommandMonitor
• func WrapCommandMonitor(mon *event.CommandMonitor, sensor instana.TracerLogger) *event.CommandMonitor

Examples

• Package
• Connect
• NewClient

Constants

const Version = "1.17.0"

Version is the instrumentation module semantic version

Functions

func Connect

func Connect(ctx context.Context, sensor instana.TracerLogger, opts ...*options.ClientOptions) (*mongo.Client, error)

Connect creates and instruments a new mongo.Client

This is a wrapper method for mongo.Connect(), see https://pkg.go.dev/go.mongodb.org/mongo-driver/mongo#Connect for details on the original method.

Example

To instrument a mongo.Client created with mongo.Connect() replace mongo.Connect() with instamongo.Connect() and pass an instana.Sensor instance to use

package main

import (
	"context"
	"log"

	instana "github.com/instana/go-sensor"
	"github.com/instana/go-sensor/instrumentation/instamongo"
	"go.mongodb.org/mongo-driver/mongo/options"
)

func main() {
	// Initialize Instana sensor
	sensor := instana.NewSensor("mongo-client")

	// Replace mongo.Connect() with instamongo.Connect and pass the sensor instance
	client, err := instamongo.Connect(context.Background(), sensor, options.Client().ApplyURI("mongodb://localhost:27017"))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Disconnect(context.Background())

	// Query MongoDB as usual using the instrumented client instance
	// ...
}

func NewClient

func NewClient(sensor instana.TracerLogger, opts ...*options.ClientOptions) (*mongo.Client, error)

NewClient returns a new instrumented mongo.Client instance

This is a wrapper method for mongo.NewClient(), see https://pkg.go.dev/go.mongodb.org/mongo-driver/mongo#NewClient for details on the original method.

Example

To instrument a mongo.Client created with mongo.NewClient() replace mongo.NewClient() with instamongo.NewClient() and pass an instana.Sensor instance to use

package main

import (
	"context"
	"log"

	instana "github.com/instana/go-sensor"
	"github.com/instana/go-sensor/instrumentation/instamongo"
	"go.mongodb.org/mongo-driver/mongo/options"
)

func main() {
	// Initialize Instana sensor
	sensor := instana.NewSensor("mongo-client")

	// Replace mongo.Connect() with instamongo.Connect and pass the sensor instance
	client, err := instamongo.NewClient(sensor, options.Client().ApplyURI("mongodb://localhost:27017"))
	if err != nil {
		log.Fatal(err)
	}

	// Use instrumented client as usual
	client.Connect(context.Background())
}

func NewCommandMonitor

func NewCommandMonitor(sensor instana.TracerLogger) *event.CommandMonitor

NewCommandMonitor creates a new event.CommandMonitor that instruments a mongo.Client with Instana.

func WrapCommandMonitor

func WrapCommandMonitor(mon *event.CommandMonitor, sensor instana.TracerLogger) *event.CommandMonitor

WrapCommandMonitor wraps an existing event.CommandMonitor to instrument a mongo.Client with Instana