README
¶
gRPC Storage Plugins
gRPC Storage Plugins currently use the Hashicorp go-plugin. This requires the implementer of a plugin to develop the "server" side of the go-plugin system. At a high level this looks like:
+----------------------------------+ +-----------------------------+
| | | |
| +-------------+ | unix-socket | +-------------+ |
| | | | | | | |
| jaeger-component | grpc-client +----------------------> grpc-server | plugin-impl |
| | | | | | | |
| +-------------+ | | +-------------+ |
| | | |
+----------------------------------+ +-----------------------------+
parent process child sub-process
Implementing a plugin
Although the instructions below are limited to Go, plugins can be implemented any language. Languages other than
Go would implement a gRPC server using the storage_v1.proto interfaces. The proto file can be found in plugin/storage/grpc/proto/.
To generate the bindings for your language you would use protoc with the appropriate xx_out= flag. This is detailed
in the protobuf documentation and you can see an example of
how it is done for Go in the top level Jaeger Makefile.
There are instructions on implementing a go-plugin server for non-Go languages in the
go-plugin non-go guide.
Take note of the required health check service.
A Go plugin is a standalone application which calls grpc.Serve(&plugin) in its main function, where the grpc package
is github.com/jaegertracing/jaeger/plugin/storage/grpc.
package main
import (
"flag"
"github.com/jaegertracing/jaeger/plugin/storage/grpc"
)
func main() {
var configPath string
flag.StringVar(&configPath, "config", "", "A path to the plugin's configuration file")
flag.Parse()
plugin := myStoragePlugin{}
grpc.Serve(&plugin)
}
A plugin must implement the StoragePlugin interface of:
type StoragePlugin interface {
SpanReader() spanstore.Reader
SpanWriter() spanstore.Writer
DependencyReader() dependencystore.Reader
}
As your plugin will be dependent on the protobuf implementation within Jaeger you will likely need to vendor your
dependencies, you can also use go.mod to achieve the same goal of pinning your plugin to a Jaeger point in time.
A simple plugin which uses the memstore storage implementation can be found in the examples directory of the top level
of the Jaeger project.
Running with a plugin
A plugin can be run using the all-in-one application within the top level cmd package of the Jaeger project. To do this
an environment variable must be set to tell the all-in-one application to use the gRPC plugin storage:
export SPAN_STORAGE_TYPE="grpc-plugin"
Once this has been set then there are two command line flags that can be used to configure the plugin. The first is
--grpc-storage-plugin.binary which is required and is the path to the plugin binary. The second is
--grpc-storage-plugin.configuration-file which is optional and is the path to the configuration file which will be
provided to your plugin as a command line flag. This command line flag is config, as can be seen in the code sample
above. An example invocation would be:
./all-in-one --grpc-storage-plugin.binary=/path/to/my/plugin --grpc-storage-plugin.configuration-file=/path/to/my/config
As well as passing configuration values via the command line through the configuration file it is also possible to use
environment variables. When you invoke all-in-one any environment variables that have been set will also be accessible
from within your plugin, this is useful if using Docker.
Logging
If the plugin uses a hclog ("github.com/hashicorp/go-hclog") logger then any logs created at the WARN or above level will be
included in the log output of the all-in-one application. Bear in mind that any logging performed before grpc.Serve
is called will not be included. As well as this grpc.Serve should likely be called at the end of your main function
as once running Jaeger may start calling to read/write spans straight away. This can mean that logging output during any
setup can be challenging.
Documentation
¶
Index ¶
- func Serve(implementation shared.StoragePlugin)
- func ServeWithGRPCServer(implementation shared.StoragePlugin, ...)
- type Factory
- func (f *Factory) AddFlags(flagSet *flag.FlagSet)
- func (f *Factory) CreateDependencyReader() (dependencystore.Reader, error)
- func (f *Factory) CreateSpanReader() (spanstore.Reader, error)
- func (f *Factory) CreateSpanWriter() (spanstore.Writer, error)
- func (f *Factory) InitFromViper(v *viper.Viper)
- func (f *Factory) Initialize(metricsFactory metrics.Factory, logger *zap.Logger) error
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Serve ¶
func Serve(implementation shared.StoragePlugin)
Serve creates a plugin configuration using the implementation of StoragePlugin and then serves it.
func ServeWithGRPCServer ¶
func ServeWithGRPCServer(implementation shared.StoragePlugin, grpcServer func([]grpc.ServerOption) *grpc.Server)
ServeWithGRPCServer creates a plugin configuration using the implementation of StoragePlugin and function to create grpcServer, and then serves it.
Types ¶
type Factory ¶
type Factory struct {
// contains filtered or unexported fields
}
Factory implements storage.Factory and creates storage components backed by a storage plugin.
func (*Factory) CreateDependencyReader ¶
func (f *Factory) CreateDependencyReader() (dependencystore.Reader, error)
CreateDependencyReader implements storage.Factory
func (*Factory) CreateSpanReader ¶
CreateSpanReader implements storage.Factory
func (*Factory) CreateSpanWriter ¶
CreateSpanWriter implements storage.Factory
func (*Factory) InitFromViper ¶
InitFromViper implements plugin.Configurable
type Options ¶
type Options struct {
Configuration config.Configuration
}
Options contains GRPC plugins configs and provides the ability to bind them to command line flags
func (*Options) InitFromViper ¶
InitFromViper initializes Options with properties from viper
Source Files
Directories