instacosmos

README

Instana instrumentation of Azure Cosmos DB SDK v2 for Go

This module contains the code for instrumenting the Azure Cosmos DB SDK based on the azcosmos library for Go.

The following operations are currently instrumented:

• Container Operations
  • CreateItem
  • DeleteItem
  • ExecuteTransactionalBatch
  • ID
  • NewQueryItemsPager
  • NewTransactionalBatch
  • PatchItem
  • Read
  • ReadItem
  • ReadThroughput
  • Replace
  • ReplaceItem
  • ReplaceThroughput
  • UpsertItem

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/instacosmos

Usage

• Utilize the following functions provided in the instacosmos module to obtain the Azure Cosmos DB client. These functions serve as wrappers for the identically named functions in the azcosmos library. Notably, in contrast to the original functions, instana.TraceLogger needs to be passed additionally.
  • NewClient
  • NewClientFromConnectionString
  • NewClientWithKey
• The aforementioned functions return an interface that offers the functionalities of azcosmos.Client. Utilizing this interface, call the NewContainer method to acquire the ContainerClient interface. This interface encompasses all the operations supported by azcosmos.ContainerClient.

Sample Usage

   var collector instana.TracerLogger
   collector = instana.InitCollector(&instana.Options{
   	Service: "cosmos-example",
   })

   // creates an KeyCredential containing the account's primary or secondary key.
   cred, err := instacosmos.NewKeyCredential(key)
   if err != nil {
   	// handle error
   }

   // creates an instance of instrumented *azcosmos.Client
   client, err := instacosmos.NewClientWithKey(collector, endpoint, cred, &azcosmos.ClientOptions{})
   if err != nil {
   	// handle error
   }

   // creates an instance of instrumented *azcosmos.Client
   containerClient, err := client.NewContainer(dbName, containerName)
   if err != nil {
   	// handle error
   }

   pk := azcosmos.NewPartitionKeyString("newPartitionKey")

   item := map[string]string{
   	"id":             "anId",
   	"value":          "2",
   	"myPartitionKey": "newPartitionKey",
   }

   marshalled, err := json.Marshal(item)
   if err != nil {
   	// handle error
   }

   // NOTE: All Cosmos DB operations requires a parent context to be passed in. 
   // Otherwise, the trace will not occur, unless the user explicitly allows opt-in exit spans without an entry span.
   itemResponse, err := containerClient.CreateItem(context.Background(), pk, marshalled, nil)
   if err != nil {
       // handle error
   }

   fmt.Printf("Item created. ActivityId %s consuming %v RU", itemResponse.ActivityID, itemResponse.RequestCharge) 

Full example

Documentation

Overview

Package instacosmos provides instrumentation for the azcosmos package in azure-sdk-for-go

Example

This example shows how to instrument Azure Cosmos DB using instacosmos library

// (c) Copyright IBM Corp. 2024

package main

import (
	"context"
	"encoding/json"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
	instana "github.com/instana/go-sensor"
	"github.com/instana/go-sensor/instrumentation/instacosmos"
)

const (
	dbName        = "trace-data"
	containerName = "spans"
)

// given empty string for example. Replace the credentials securely in your code
var (
	cosmosEndpoint = ""
	cosmosKey      = ""
)

// This example shows how to instrument Azure Cosmos DB using instacosmos library
func main() {

	t := instana.InitCollector(&instana.Options{
		Service: "cosmos-example",
	})

	// creates an KeyCredential containing the account's primary or secondary key.
	cred, err := instacosmos.NewKeyCredential(cosmosKey)
	if err != nil {
		log.Fatal("Failed to create KeyCredential:", err)
	}

	client, err := instacosmos.NewClientWithKey(t, cosmosEndpoint, cred, &azcosmos.ClientOptions{})
	if err != nil {
		log.Fatal("Failed to create cosmos DB client:", err)
	}

	// Create container client instance
	containerClient, err := client.NewContainer(dbName, containerName)
	if err != nil {
		log.Fatal("Failed to create a container client:", err)
	}

	pk := containerClient.NewPartitionKeyString("newPartitionKey")

	item := map[string]string{
		"id":             "anId",
		"value":          "2",
		"myPartitionKey": "newPartitionKey",
	}

	marshalled, err := json.Marshal(item)
	if err != nil {
		log.Fatal("Failed to marshal span data:", err)
	}

	// create the item in the Cosmos DB container
	// NOTE: All Cosmos DB operations requires a parent context to be passed in.
	// Otherwise, the trace will not occur, unless the user explicitly allows opt-in exit spans without an entry span.
	itemResponse, err := containerClient.CreateItem(context.Background(), pk, marshalled, nil)
	if err != nil {
		log.Print("Failed to create the item:", err)
	}

	log.Printf("Status %d. Item %v created. ActivityId %s. Consuming %v Request Units.\n",
		itemResponse.RawResponse.StatusCode,
		pk, itemResponse.ActivityID,
		itemResponse.RequestCharge)
}

Index

• Constants
• func NewKeyCredential(key string) (azcosmos.KeyCredential, error)
• type Client
  • func NewClient(collector instana.TracerLogger, endpoint string, cred azcore.TokenCredential, ...) (Client, error)
  • func NewClientFromConnectionString(collector instana.TracerLogger, connectionString string, ...) (Client, error)
  • func NewClientWithKey(collector instana.TracerLogger, endpoint string, cred azcosmos.KeyCredential, ...) (Client, error)
• type ContainerClient
• type PartitionKey
  • func NewPartitionKey(val string) PartitionKey

Examples

• Package

Constants

const (
	Query   = "Query"
	Write   = "Write"
	Execute = "Execute"
	Update  = "Update"
	Upsert  = "Upsert"
	Replace = "Replace"
)

data operation types

const Version = "1.7.0"

Version is the instrumentation module semantic version

Functions

func NewKeyCredential

func NewKeyCredential(key string) (azcosmos.KeyCredential, error)

NewKeyCredential creates an KeyCredential containing the account's primary or secondary key.

Types

type Client

type Client interface {
	Endpoint() string
	NewContainer(databaseID string, containerID string) (ContainerClient, error)
	NewDatabase(id string) (*azcosmos.DatabaseClient, error)
	CreateDatabase(
		ctx context.Context,
		databaseProperties azcosmos.DatabaseProperties,
		o *azcosmos.CreateDatabaseOptions) (azcosmos.DatabaseResponse, error)
	NewQueryDatabasesPager(query string, o *azcosmos.QueryDatabasesOptions) *runtime.Pager[azcosmos.QueryDatabasesResponse]
}

Client is the interface that wraps the methods of *azcosmos.Client

func NewClient

func NewClient(collector instana.TracerLogger, endpoint string, cred azcore.TokenCredential, o *azcosmos.ClientOptions) (Client, error)

NewClient creates an instance of instrumented *azcosmos.Client endpoint - The cosmos service endpoint to use. cred - The credential used to authenticate with the cosmos service. options - Optional Cosmos client options. Pass nil to accept default values.

func NewClientFromConnectionString

func NewClientFromConnectionString(collector instana.TracerLogger, connectionString string, o *azcosmos.ClientOptions) (Client, error)

NewClientFromConnectionString creates an instance of instrumented *azcosmos.Client connectionString - The cosmos service connection string. options - Optional Cosmos client options. Pass nil to accept default values.

func NewClientWithKey

func NewClientWithKey(collector instana.TracerLogger,
	endpoint string,
	cred azcosmos.KeyCredential,
	o *azcosmos.ClientOptions) (Client, error)

NewClientWithKey creates an instance of instrumented *azcosmos.Client endpoint - The cosmos service endpoint to use. cred - The credential used to authenticate with the cosmos service. options - Optional Cosmos client options. Pass nil to accept default values.

type ContainerClient

type ContainerClient interface {
	PartitionKey
	DatabaseID() string
	CreateItem(
		ctx context.Context,
		partitionKey azcosmos.PartitionKey,
		item []byte,
		o *azcosmos.ItemOptions) (azcosmos.ItemResponse, error)
	DeleteItem(ctx context.Context,
		partitionKey azcosmos.PartitionKey,
		itemId string,
		o *azcosmos.ItemOptions) (azcosmos.ItemResponse, error)
	ExecuteTransactionalBatch(ctx context.Context,
		b azcosmos.TransactionalBatch,
		o *azcosmos.TransactionalBatchOptions) (azcosmos.TransactionalBatchResponse, error)
	ID() string
	NewQueryItemsPager(query string,
		partitionKey azcosmos.PartitionKey,
		o *azcosmos.QueryOptions) *runtime.Pager[azcosmos.QueryItemsResponse]
	NewTransactionalBatch(partitionKey azcosmos.PartitionKey) azcosmos.TransactionalBatch
	PatchItem(
		ctx context.Context,
		partitionKey azcosmos.PartitionKey,
		itemId string,
		ops azcosmos.PatchOperations,
		o *azcosmos.ItemOptions) (azcosmos.ItemResponse, error)
	Read(
		ctx context.Context,
		o *azcosmos.ReadContainerOptions) (azcosmos.ContainerResponse, error)
	ReadItem(
		ctx context.Context,
		partitionKey azcosmos.PartitionKey,
		itemId string,
		o *azcosmos.ItemOptions) (azcosmos.ItemResponse, error)
	ReadThroughput(
		ctx context.Context,
		o *azcosmos.ThroughputOptions) (azcosmos.ThroughputResponse, error)
	Replace(
		ctx context.Context,
		containerProperties azcosmos.ContainerProperties,
		o *azcosmos.ReplaceContainerOptions) (azcosmos.ContainerResponse, error)
	ReplaceItem(
		ctx context.Context,
		partitionKey azcosmos.PartitionKey,
		itemId string,
		item []byte,
		o *azcosmos.ItemOptions) (azcosmos.ItemResponse, error)
	ReplaceThroughput(
		ctx context.Context,
		throughputProperties azcosmos.ThroughputProperties,
		o *azcosmos.ThroughputOptions) (azcosmos.ThroughputResponse, error)
	UpsertItem(
		ctx context.Context,
		partitionKey azcosmos.PartitionKey,
		item []byte,
		o *azcosmos.ItemOptions) (azcosmos.ItemResponse, error)
}

ContainerClient is the interface that wraps the methods of *azcosmos.ContainerClient

type PartitionKey

type PartitionKey interface {
	NewPartitionKeyString(value string) azcosmos.PartitionKey
	NewPartitionKeyBool(value bool) azcosmos.PartitionKey
	NewPartitionKeyNumber(value float64) azcosmos.PartitionKey
	// contains filtered or unexported methods
}

PartitionKey is the interface that wraps partition key generator functions for different types

func NewPartitionKey

func NewPartitionKey(val string) PartitionKey

NewPartitionKey returns instance of pk which implements PartitionKey interface