package
0.3.1
Repository: https://github.com/neblic/platform.git
Documentation: pkg.go.dev

# README

Go sampler module

The Go Sampler module allows you to get Data Samples from your Go services.

gRPC interceptors

The Go library also provides a package to easily add Samplers as gRPC interceptors. This will automatically add Samplers in each gRPC method that will intercept all requests and responses.

Supported encodings

EncodingDescription
ProtobufIt can efficiently process proto.Message objects if the Protobuf message definition is provided.
Go native objectOnly capable of accessing exported fields. This is a limitation of the Go language.
JSONA string containing a JSON object.

Warning The next section is better read in the documentation page since it is post-processed to include code snippets from tests

Usage

!!! note All code snippets have error handling omitted for brevity

To add Samplers in your code that export Data Samples you first need to initialize a Provider. A Provider receives a configuration that is then used to configure and initialize all the Samplers in your application.

import (
--8<-- "./sampler/test/docs/provider_test.go:ProviderInitImport"
)

--8<-- "./sampler/test/docs/provider_test.go:ProviderInit"

To see details about the required settings and available options, see this page.

Once the Provider is initialized, you can use it to initialize Samplers. If you have registered the provider as global, you can simply call the Sampler method from anywhere in your application. If not, you will need to call the Sampler method of your provider. They both have the same signature so the following explanation works for both options.

!!! Info It is not required to first initialize and register the Provider as global before creating Samplers. If a Sampler is initialized using the global provider before a Provider is registered, it will return a stubbed Sampler with no-op methods. Once the Provider is registered, it will internally replace the no-op stub with the real Sampler. This happens transparently for the application.

import (
--8<-- "./sampler/test/docs/sampler_test.go:SamplerInitImport"
)

--8<-- "./sampler/test/docs/sampler_test.go:SamplerInit"

To see what other schemas the Go Sampler supports, check this Godoc page.

Once you have initialized the Sampler, you can call any of its methods to have it evaluate a Data Sample. It will then be evaluated by any configured Sampling Rule and exported if there is a match.

!!! Warning You need to be mindful of what methods you use to sample data. Depending on the schema provided when the Sampler is initialized, some methods will work better or faster than others.

As a rule of thumb, you want to provide a schema if you have it since this allows the `Sampler` to internally optimize how it evaluates the `Sampling Rules`. If you do not have it, a sampler configured with a `DynamicSchema` is capable of processing any type data using any of the sampling methods. See the [Godoc](https://pkg.go.dev/github.com/neblic/platform/sampler/defs) documentation for details.
--8<-- "./sampler/test/docs/sampler_test.go:SampleData"

In this example, since the Sampler was initialized with a DynamicSchema, it is best to use the method SampleJson() or SampleNative(). These sampling methods are designed to work with samples that do not have a fixed or known schema.

gRPC interceptor

If you use gRPC servers or clients in your services, you can make use of a gRPC interceptor. They will automatically create Samplers that will efficiently intercept all requests and responses.

Internally, they create Samplers with a ProtoSchema so they do not need to deserialize the Protobuf message to evaluate its contents.

To use it, you need to initialize the interceptor and provide it when initializing the gRPC connection

import (
--8<-- "./sampler/test/docs/interceptor_test.go:InterceptorInitImport"
)

--8<-- "./sampler/test/docs/interceptor_test.go:InterceptorInit"

# Packages

No description provided by the author
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

New creates a new sampler using the global provider.
NewProvider creates a new sampler provider capable of creating new samplers.
Sample samples the given data sample using the given sampler name and schema.
SetProvider sets the global provider.
WithBearerAuth sets authorization based on a Bearer token.
WithInitalValueDigest enables the computation of value digest.
WithInitialDeterministicSamplingIn defines a deterministic sampling strategy which will be applied when a sample is received and before processing it in any way (e.g.
WithInitialLimiterInLimit sets the initial limiter in rate limit.
WithInitialLimiterInLimit sets the initial limiter in rate limit.
WithInitalStructDigest enables the computation of struct digest.
WithLogger provides a logger instance to log the Provider and Sampler activity.
WithoutDefaultInitialConfig avoids setting the default 'all' stream and digest.
WithErrorChannel received a channel where Sampler errors will be sent.
WithTags can be used to specify tags to classify the Sampler or to specify its type.
WithTLS enables TLS connections with the server.
WithUpdateStatsPeriod specifies the period to send sampler stats to server If the provided period is less than a second, it will be set to 1 second.

# Constants

re-exported known tags.
No description provided by the author
DLQTag is used to tag samples that are sent to a dead letter queue Automatically enables an event that notifies when a sample is sent to a DLQ.
re-exported known tags.
re-exported known tags.
re-exported known tags.

# Structs

No description provided by the author

# Interfaces

No description provided by the author
Provider defines a sampler provider object capable of creating new samplers.
No description provided by the author
Sampler defines the sampler public interface.