opentelemetry

opentelemetry

import "github.com/blueprint-uservices/blueprint/plugins/opentelemetry"

Package OpenTelemetry provides a Blueprint plugin for instrumenting services and collecting OpenTelemetry traces. The plugin provides APIs to be used in the wiring specification for the following:

1. to wrap the service with an OpenTelemetry wrapper to generate OT compatible traces by starting and stopping client spans for remote calls between services and correctly propagating context between services. The traces are then exported to a collector client such as jaeger or zipkin.
2. to install an opentelemetry trace-based event logger for a go process. The logger adds all the logs as events to the current active span. If no active span exists, then no events are logged.

Once the application is instrumented with these plugins, traces will be generated by the instrumented services, and collected centrally at the trace collector.

Wiring Usage

To instrument services with opentelemetry instrumentation:

opentelemetry.Instrument(spec, "my_service", "collector_name")

Calling Instrument will generate client and server side wrappers responsible for starting and stopping spans as well as correctly propagating the context across service boundaries.

To redirect a process's logging statements to opentelemetry generated spans:

opentelemetry.Logger(spec, "my_process")

Calling Logger will redirect all logging statements generated by the process to opentelemetry where the log statements will be converted into opentelemetry Events and added to the list of events for the current active span.

In order to generate complete end-to-end traces of the application, all services of the application need to be instrumented with OpenTelemetry. If the plugin is only applied to a subset of services, the application will run, but the traces produced won't be end-to-end and won't be useful. The plugin does not support instrumenting clients for backends such as databases, caches, queues, etc. If needed, please consider submitting a PR or contacting the maintainers via google groups or on slack.

Artifacts Generated

1. The package generates client and server side wrappers for instrumented services that contain opentelemetry instrumentation (context propagation, creation of spans). The generated clients handle context propagation correctly on both the server and client sides. The implementation of the logger is located at runtime/plugins/opentelemetry and if the opentelemetry logger is installed for a process then this logger is used.

Example usage (for complete instrumentation):

Wiring Example

func applyOTelOptions() {
	jaeger.Container(spec, "jaeger")
	for _, service := range serviceNames {
		opentelemetry.Instrument(spec, service)
	}
	for _, proc := range processNames {
		opentelemetry.Logger(spec, proc)
	}
}

See the ot\_logger wiring spec for the Leaf application for a complete example

Accessing Traces

The traces are generated and sent to the configured (zipkin or jaeger) collector. Each collector exposes a web UI which can be used to access end-to-end traces. For Zipkin, the UI is hosted at port 9411 by default and for Jaeger, the UI is hosted at port 16686 by default.

Index

• func Instrument(spec wiring.WiringSpec, serviceName string, collectorName string)
• func Logger(spec wiring.WiringSpec, processName string) string
• type OTTraceLogger
  • func (node *OTTraceLogger) AddInstantiation(builder golang.NamespaceBuilder) error
  • func (node *OTTraceLogger) AddInterfaces(builder golang.ModuleBuilder) error
  • func (node *OTTraceLogger) AddToWorkspace(builder golang.WorkspaceBuilder) error
  • func (node *OTTraceLogger) GetInterface(ctx ir.BuildContext) (service.ServiceInterface, error)
  • func (node *OTTraceLogger) ImplementsGolangNode()
  • func (node *OTTraceLogger) Name() string
  • func (node *OTTraceLogger) String() string
• type OpenTelemetryClientWrapper
  • func (node *OpenTelemetryClientWrapper) AddInstantiation(builder golang.NamespaceBuilder) error
  • func (node *OpenTelemetryClientWrapper) AddInterfaces(builder golang.ModuleBuilder) error
  • func (node *OpenTelemetryClientWrapper) GenerateFuncs(builder golang.ModuleBuilder) error
  • func (node *OpenTelemetryClientWrapper) GetInterface(ctx ir.BuildContext) (service.ServiceInterface, error)
  • func (node *OpenTelemetryClientWrapper) ImplementsGolangNode()
  • func (node *OpenTelemetryClientWrapper) ImplementsGolangService()
  • func (node *OpenTelemetryClientWrapper) Name() string
  • func (node *OpenTelemetryClientWrapper) String() string
• type OpenTelemetryCollectorInterface
• type OpenTelemetryServerWrapper
  • func (node *OpenTelemetryServerWrapper) AddInstantiation(builder golang.NamespaceBuilder) error
  • func (node *OpenTelemetryServerWrapper) AddInterfaces(builder golang.ModuleBuilder) error
  • func (node *OpenTelemetryServerWrapper) GenerateFuncs(builder golang.ModuleBuilder) error
  • func (node *OpenTelemetryServerWrapper) GetInterface(ctx ir.BuildContext) (service.ServiceInterface, error)
  • func (node *OpenTelemetryServerWrapper) ImplementsGolangNode()
  • func (node *OpenTelemetryServerWrapper) ImplementsGolangService()
  • func (node *OpenTelemetryServerWrapper) Name() string
  • func (node *OpenTelemetryServerWrapper) String() string

func Instrument

func Instrument(spec wiring.WiringSpec, serviceName string, collectorName string)

Instrument can be used by wiring specs to instrument `serviceName` with OpenTelemetry. This can only be done if `serviceName` is a service declared in the wiring spec using [workflow.Define] and has not yet been deployed over the network using grpc, thrift, or http.

This call will configure the generated clients on server and client side to use the exporter provided by the custom collector indicated by the `collectorName`. The `collectorName` must already be declared in the wiring spec.

func Logger

func Logger(spec wiring.WiringSpec, processName string) string

Logger can be used by wiring specs to install a process-level ot logger for process `processName` to be used in tandem with an OT Tracer. Replaces the existing logger installed for the process.

Logs are added as `ot.Events` to the current span and will be added as events to the current span and won't appear in stdout.

If no current span is being recorded, then no events will be generated. Use `Instrument` to ensure that all services in a process are instrumented with OpenTelemetry and are creating active spans.

Wiring Spec Usage:

opentelemetry.Logger(spec, "my_process")

type OTTraceLogger

Blueprint IR Node that represents a process-level OT trace logger

type OTTraceLogger struct {
    golang.Node
    golang.Instantiable

    LoggerName string
    Spec       *workflowspec.Service
}

func (*OTTraceLogger) AddInstantiation

func (node *OTTraceLogger) AddInstantiation(builder golang.NamespaceBuilder) error

Implements golang.Instantiable

func (*OTTraceLogger) AddInterfaces

func (node *OTTraceLogger) AddInterfaces(builder golang.ModuleBuilder) error

Implements golang.ProvidesInterface

func (*OTTraceLogger) AddToWorkspace

func (node *OTTraceLogger) AddToWorkspace(builder golang.WorkspaceBuilder) error

Implements golang.ProvidesModule

func (*OTTraceLogger) GetInterface

func (node *OTTraceLogger) GetInterface(ctx ir.BuildContext) (service.ServiceInterface, error)

Implements golang.ProvidesInterface

func (*OTTraceLogger) ImplementsGolangNode

func (node *OTTraceLogger) ImplementsGolangNode()

Implements ir.IRNode

func (*OTTraceLogger) Name

func (node *OTTraceLogger) Name() string

Implements ir.IRNode

func (*OTTraceLogger) String

func (node *OTTraceLogger) String() string

Implements ir.IRNode

type OpenTelemetryClientWrapper

Blueprint IR Node that wraps the client-side of a service to generate ot compatible logs

type OpenTelemetryClientWrapper struct {
    golang.Service
    golang.GeneratesFuncs

    WrapperName string

    Wrapped   golang.Service
    Collector OpenTelemetryCollectorInterface
    // contains filtered or unexported fields
}

func (*OpenTelemetryClientWrapper) AddInstantiation

func (node *OpenTelemetryClientWrapper) AddInstantiation(builder golang.NamespaceBuilder) error

Part of code generation compilation pass; provides instantiation snippet

func (*OpenTelemetryClientWrapper) AddInterfaces

func (node *OpenTelemetryClientWrapper) AddInterfaces(builder golang.ModuleBuilder) error

Part of code generation compilation pass; creates the interface definition code for the wrapper, and any new generated structs that are exposed and can be used by other IRNodes

func (*OpenTelemetryClientWrapper) GenerateFuncs

func (node *OpenTelemetryClientWrapper) GenerateFuncs(builder golang.ModuleBuilder) error

Part of code generation compilation pass; provides implementation of interfaces from GenerateInterfaces

func (*OpenTelemetryClientWrapper) GetInterface

func (node *OpenTelemetryClientWrapper) GetInterface(ctx ir.BuildContext) (service.ServiceInterface, error)

func (*OpenTelemetryClientWrapper) ImplementsGolangNode

func (node *OpenTelemetryClientWrapper) ImplementsGolangNode()

func (*OpenTelemetryClientWrapper) ImplementsGolangService

func (node *OpenTelemetryClientWrapper) ImplementsGolangService()

func (*OpenTelemetryClientWrapper) Name

func (node *OpenTelemetryClientWrapper) Name() string

func (*OpenTelemetryClientWrapper) String

func (node *OpenTelemetryClientWrapper) String() string

type OpenTelemetryCollectorInterface

Interface that indicates if an IRNode implements the OTCollector interface All custom collector clients **must** implement this interface

type OpenTelemetryCollectorInterface interface {
    golang.Node
    golang.Instantiable
    ImplementsOTCollectorClient()
}

type OpenTelemetryServerWrapper

Blueprint IR Node that wraps the server-side of a service to generate ot compatible logs

type OpenTelemetryServerWrapper struct {
    golang.Service
    golang.Instantiable
    golang.GeneratesFuncs

    WrapperName string

    Wrapped   golang.Service
    Collector OpenTelemetryCollectorInterface
    // contains filtered or unexported fields
}

func (*OpenTelemetryServerWrapper) AddInstantiation

func (node *OpenTelemetryServerWrapper) AddInstantiation(builder golang.NamespaceBuilder) error

Part of code generation compilation pass; provides instantiation snippet

func (*OpenTelemetryServerWrapper) AddInterfaces

func (node *OpenTelemetryServerWrapper) AddInterfaces(builder golang.ModuleBuilder) error

Part of code generation compilation pass; creates the interface definition code for the wrapper, and any new generated structs that are exposed and can be used by other IRNodes

func (*OpenTelemetryServerWrapper) GenerateFuncs

func (node *OpenTelemetryServerWrapper) GenerateFuncs(builder golang.ModuleBuilder) error

Part of code generation compilation pass; provides implementation of interfaces from GenerateInterfaces

func (*OpenTelemetryServerWrapper) GetInterface

func (node *OpenTelemetryServerWrapper) GetInterface(ctx ir.BuildContext) (service.ServiceInterface, error)

func (*OpenTelemetryServerWrapper) ImplementsGolangNode

func (node *OpenTelemetryServerWrapper) ImplementsGolangNode()

func (*OpenTelemetryServerWrapper) ImplementsGolangService

func (node *OpenTelemetryServerWrapper) ImplementsGolangService()

func (*OpenTelemetryServerWrapper) Name

func (node *OpenTelemetryServerWrapper) Name() string

func (*OpenTelemetryServerWrapper) String

func (node *OpenTelemetryServerWrapper) String() string

Generated by gomarkdoc