es

README

ElasticSearch Support

This provides a storage backend for Jaeger using Elasticsearch. More information is available on the Jaeger documentation website.

Indices

Indices will be created depending on the spans timestamp. i.e., a span with a timestamp on 2017/04/21 will be stored in an index named jaeger-2017-04-21. ElasticSearch also has no support for TTL, so there exists a script ./esCleaner.py that deletes older indices automatically. The Elastic Curator can also be used instead to do a similar job.

Using ./esCleaner.py

The script is using python3. All dependencies can be installed with: python3 -m pip install elasticsearch elasticsearch-curator.

Parameters:

• Environment variable TIMEOUT that sets the timeout in seconds for indices deletion (default: 120)
• Optional environment variable ES_USERNAME and ES_PASSWORD
• a number that will delete any indices older than that number in days
• ElasticSearch hostnames
• Example usage: TIMEOUT=120 ./esCleaner.py 4 localhost:9200

Timestamps

Because ElasticSearch's Date datatype has only millisecond granularity and Jaeger requires microsecond granularity, Jaeger spans' StartTime is saved as a long type. The conversion is done automatically.

Nested fields (tags)

Tags are nested fields in the ElasticSearch schema used for Jaeger. This allows for better search capabilities and data retention. However, because ElasticSearch creates a new document for every nested field, there is currently a limit of 50 nested fields per document.

Shards and Replicas

Number of shards and replicas per index can be specified as parameters to the writer and/or through configs under ./pkg/es/config/config.go. If not specified, it defaults to ElasticSearch defaults: 5 shards and 1 replica. This article goes into more information about choosing how many shards should be chosen for optimization.

Limitations

Tag query over multiple spans

This plugin queries against spans. This means that all tags in a query must lie under the same span for a query to successfully return a trace.

Case-sensitivity

Queries are case-sensitive. For example, if a document with service name ABC is searched using a query abc, the document will not be retrieved.

Testing

To locally test the ElasticSearch storage plugin,

• have ElasticSearch running on port 9200
• run STORAGE=es make storage-integration-test in the top folder.

All integration tests also run on pull request via GitHub Actions. This integration test is against ElasticSearch v5.6.16, v6.8.2 and v7.3.0.

• The script used in GitHub Actions can be found under scripts/es-integration-test.sh, and that script be run from the top folder to integration test ElasticSearch as well. This script requires Docker to be running.

Adding tests

Integration test framework for storage lie under ../integration. Add to ../integration/fixtures/traces/*.json and ../integration/fixtures/queries.json to add more trace cases.

Documentation

Index

• func FixMapping(tb es.TemplateBuilder, mapping string, shards, replicas int64, esPrefix string, ...) (string, error)
• func GetDependenciesMappings(tb es.TemplateBuilder, shards, replicas int64, esVersion uint) (string, error)
• func GetSpanServiceMappings(tb es.TemplateBuilder, shards, replicas int64, esVersion uint, esPrefix string, ...) (string, string, error)
• func LoadMapping(name string) string
• type Factory
  • func NewFactory() *Factory
  • func (f *Factory) AddFlags(flagSet *flag.FlagSet)
  • func (f *Factory) Close() error
  • func (f *Factory) CreateArchiveSpanReader() (spanstore.Reader, error)
  • func (f *Factory) CreateArchiveSpanWriter() (spanstore.Writer, error)
  • func (f *Factory) CreateDependencyReader() (dependencystore.Reader, error)
  • func (f *Factory) CreateSpanReader() (spanstore.Reader, error)
  • func (f *Factory) CreateSpanWriter() (spanstore.Writer, error)
  • func (f *Factory) InitFromOptions(o Options)
  • func (f *Factory) InitFromViper(v *viper.Viper)
  • func (f *Factory) Initialize(metricsFactory metrics.Factory, logger *zap.Logger) error
• type Options
  • func NewOptions(primaryNamespace string, otherNamespaces ...string) *Options
  • func NewOptionsFromConfig(primary config.Configuration, archive config.Configuration) *Options
  • func (opt *Options) AddFlags(flagSet *flag.FlagSet)
  • func (opt *Options) Get(namespace string) *config.Configuration
  • func (opt *Options) GetPrimary() *config.Configuration
  • func (opt *Options) InitFromViper(v *viper.Viper)

Functions

func FixMapping

func FixMapping(tb es.TemplateBuilder, mapping string, shards, replicas int64, esPrefix string, useILM bool) (string, error)

FixMapping parses the index mappings with given values and returns parsed template as string

func GetDependenciesMappings

func GetDependenciesMappings(tb es.TemplateBuilder, shards, replicas int64, esVersion uint) (string, error)

GetDependenciesMappings returns dependencies mappings

func GetSpanServiceMappings

func GetSpanServiceMappings(tb es.TemplateBuilder, shards, replicas int64, esVersion uint, esPrefix string, useILM bool) (string, string, error)

GetSpanServiceMappings returns span and service mappings

func LoadMapping

func LoadMapping(name string) string

LoadMapping returns index mappings from go assets as strings

Types

type Factory

type Factory struct {
	Options *Options
	// contains filtered or unexported fields
}

Factory implements storage.Factory for Elasticsearch backend.

func NewFactory

func NewFactory() *Factory

NewFactory creates a new Factory.

func (*Factory) AddFlags

func (f *Factory) AddFlags(flagSet *flag.FlagSet)

AddFlags implements plugin.Configurable

func (*Factory) Close

func (f *Factory) Close() error

Close closes the resources held by the factory

func (*Factory) CreateArchiveSpanReader

func (f *Factory) CreateArchiveSpanReader() (spanstore.Reader, error)

CreateArchiveSpanReader implements storage.ArchiveFactory

func (*Factory) CreateArchiveSpanWriter

func (f *Factory) CreateArchiveSpanWriter() (spanstore.Writer, error)

CreateArchiveSpanWriter implements storage.ArchiveFactory

func (*Factory) CreateDependencyReader

func (f *Factory) CreateDependencyReader() (dependencystore.Reader, error)

CreateDependencyReader implements storage.Factory

func (*Factory) CreateSpanReader

func (f *Factory) CreateSpanReader() (spanstore.Reader, error)

CreateSpanReader implements storage.Factory

func (*Factory) CreateSpanWriter

func (f *Factory) CreateSpanWriter() (spanstore.Writer, error)

CreateSpanWriter implements storage.Factory

func (*Factory) InitFromOptions

func (f *Factory) InitFromOptions(o Options)

InitFromOptions configures factory from Options struct.

func (*Factory) InitFromViper

func (f *Factory) InitFromViper(v *viper.Viper)

InitFromViper implements plugin.Configurable

func (*Factory) Initialize

func (f *Factory) Initialize(metricsFactory metrics.Factory, logger *zap.Logger) error

Initialize implements storage.Factory

type Options

type Options struct {
	Primary namespaceConfig `mapstructure:",squash"`
	// contains filtered or unexported fields
}

Options contains various type of Elasticsearch configs and provides the ability to bind them to command line flag and apply overlays, so that some configurations (e.g. archive) may be underspecified and infer the rest of its parameters from primary.

func NewOptions

func NewOptions(primaryNamespace string, otherNamespaces ...string) *Options

NewOptions creates a new Options struct.

func NewOptionsFromConfig

func NewOptionsFromConfig(primary config.Configuration, archive config.Configuration) *Options

NewOptionsFromConfig creates Options from primary and archive config

func (*Options) AddFlags

func (opt *Options) AddFlags(flagSet *flag.FlagSet)

AddFlags adds flags for Options

func (*Options) Get

func (opt *Options) Get(namespace string) *config.Configuration

Get returns auxiliary named configuration.

func (*Options) GetPrimary

func (opt *Options) GetPrimary() *config.Configuration

GetPrimary returns primary configuration.

func (*Options) InitFromViper

func (opt *Options) InitFromViper(v *viper.Viper)

InitFromViper initializes Options with properties from viper