otlp

README

OTLP Translator

This module provides an easy to use way of converting OTLP requests into easily ingestible data structures (eg []map[string]interface{}). This makes consuming the OTLP wire format easier and more consistent.

Traces

You can either provide the OTLP trace request directly or a HTTP request object that contains the request in the body.

// HTTP Request
ri := GetRequestInfoFromHttpHeaders(request.header) // (request.header http.Header)
res, err := TranslateHttpTraceRequest(request.body, ri) //(request.body io.Reader, ri RequestInfo)

// OTLP Trace gRPC
res, err := TranslateGrpcTraceRequest(request) // (request *collectorTrace.ExportTraceServiceRequest)

Common

The library also includes generic ways to extract request information (API Key, Dataset, etc).

// HTTP request
requestInfo := GetRequestInfoFromHttpHeaders(header) // (header http.Header)

// gRPC request context
requestInfo := GetRequestInfoFromGrpcMetadata(ctx) // (ctx context.Context)

Documentation

Index

• Variables
• func AddAttributesToMap(ctx context.Context, attrs map[string]interface{}, ...)
• func AsGRPCError(e error) error
• func AsJson(e error) string
• func BytesToSpanID(spanID []byte) string
• func BytesToTraceID(traceID []byte) string
• func GetSupportedContentEncodings() []string
• func GetSupportedContentTypes() []string
• func IsClassicApiKey(key string) bool
• func IsContentTypeSupported(contentType string) bool
• func WriteOtlpHttpFailureResponse(w http.ResponseWriter, r *http.Request, err OTLPError) error
• func WriteOtlpHttpLogSuccessResponse(w http.ResponseWriter, r *http.Request) error
• func WriteOtlpHttpMetricSuccessResponse(w http.ResponseWriter, r *http.Request) error
• func WriteOtlpHttpResponse(w http.ResponseWriter, r *http.Request, statusCode int, m proto.Message) error
• func WriteOtlpHttpTraceSuccessResponse(w http.ResponseWriter, r *http.Request) error
• type Batch
• type Event
• type OTLPError
  • func (e OTLPError) Error() string
• type RequestInfo
  • func GetRequestInfoFromGrpcMetadata(ctx context.Context) RequestInfo
  • func GetRequestInfoFromHttpHeaders(header http.Header) RequestInfo
  • func (ri *RequestInfo) ValidateLogsHeaders() error
  • func (ri *RequestInfo) ValidateMetricsHeaders() error
  • func (ri *RequestInfo) ValidateTracesHeaders() error
• type TranslateOTLPRequestResult
  • func TranslateLogsRequest(ctx context.Context, request *collectorLogs.ExportLogsServiceRequest, ...) (*TranslateOTLPRequestResult, error)
  • func TranslateLogsRequestFromReader(ctx context.Context, body io.ReadCloser, ri RequestInfo) (*TranslateOTLPRequestResult, error)
  • func TranslateTraceRequest(ctx context.Context, request *collectorTrace.ExportTraceServiceRequest, ...) (*TranslateOTLPRequestResult, error)
  • func TranslateTraceRequestFromReader(ctx context.Context, body io.ReadCloser, ri RequestInfo) (*TranslateOTLPRequestResult, error)

Variables

var (
	ErrInvalidContentType   = OTLPError{"unsupported content-type, valid types are: " + strings.Join(GetSupportedContentTypes(), ", "), http.StatusUnsupportedMediaType, codes.Unimplemented}
	ErrFailedParseBody      = OTLPError{"failed to parse OTLP request body", http.StatusBadRequest, codes.Internal}
	ErrMissingAPIKeyHeader  = OTLPError{"missing 'x-honeycomb-team' header", http.StatusUnauthorized, codes.Unauthenticated}
	ErrMissingDatasetHeader = OTLPError{"missing 'x-honeycomb-dataset' header", http.StatusUnauthorized, codes.Unauthenticated}
)

Functions

func AddAttributesToMap

func AddAttributesToMap(ctx context.Context, attrs map[string]interface{}, attributes []*common.KeyValue)

AddAttributesToMap adds attributes to a map, extracting the underlying attribute data type. Supported types are string, bool, double, int, bytes, array, and kvlist. kvlist attributes are flattened to a depth of (maxDepth), if the depth is exceeded, the attribute is added as a JSON string. Bytes and array values are always added as JSON strings.

func AsGRPCError

func AsGRPCError(e error) error

func AsJson

func AsJson(e error) string

func BytesToSpanID

func BytesToSpanID(spanID []byte) string

func BytesToTraceID

func BytesToTraceID(traceID []byte) string

BytesToTraceID returns an ID suitable for use for spans and traces. Before encoding the bytes as a hex string, we want to handle cases where we are given 128-bit IDs with zero padding, e.g. 0000000000000000f798a1e7f33c8af6. There are many ways to achieve this, but careful benchmarking and testing showed the below as the most performant, avoiding memory allocations and the use of flexible but expensive library functions. As this is hot code, it seemed worthwhile to do it this way.

func GetSupportedContentEncodings

func GetSupportedContentEncodings() []string

List of HTTP Content Encodings supported for OTLP ingest.

func GetSupportedContentTypes

func GetSupportedContentTypes() []string

List of HTTP Content Types supported for OTLP ingest.

func IsClassicApiKey

func IsClassicApiKey(key string) bool

IsClassicApiKey checks if the given API key is a Classic API key.

func IsContentTypeSupported

func IsContentTypeSupported(contentType string) bool

Check whether we support a given HTTP Content Type for OTLP.

func WriteOtlpHttpFailureResponse

func WriteOtlpHttpFailureResponse(w http.ResponseWriter, r *http.Request, err OTLPError) error

WriteOtlpHttpFailureResponse is a quick way to write an otlp response for an error. It calls WriteOtlpHttpResponse, using the error's HttpStatusCode and building a Status using the error's string.

func WriteOtlpHttpLogSuccessResponse

func WriteOtlpHttpLogSuccessResponse(w http.ResponseWriter, r *http.Request) error

WriteOtlpHttpLogSuccessResponse is a quick way to write an otlp success response for a trace request. It calls WriteOtlpHttpResponse, using the 200 status code and an empty ExportLogsServiceResponse

func WriteOtlpHttpMetricSuccessResponse

func WriteOtlpHttpMetricSuccessResponse(w http.ResponseWriter, r *http.Request) error

WriteOtlpHttpMetricSuccessResponse is a quick way to write an otlp success response for a metric request. It calls WriteOtlpHttpResponse, using the 200 status code and an empty ExportMetricsServiceResponse

func WriteOtlpHttpResponse

func WriteOtlpHttpResponse(w http.ResponseWriter, r *http.Request, statusCode int, m proto.Message) error

WriteOtlpHttpResponse writes a compliant OTLP HTTP response to the given http.ResponseWriter based on the provided `contentType`. If an error occurs while marshalling to either json or proto it is returned before the http.ResponseWriter is updated. If an error occurs while writing to the http.ResponseWriter it is ignored. If an invalid content type is provided, a 415 Unsupported Media Type via text/plain is returned.

func WriteOtlpHttpTraceSuccessResponse

func WriteOtlpHttpTraceSuccessResponse(w http.ResponseWriter, r *http.Request) error

WriteOtlpHttpTraceSuccessResponse is a quick way to write an otlp success response for a trace request. It calls WriteOtlpHttpResponse, using the 200 status code and an empty ExportTraceServiceResponse

Types

type Batch

type Batch struct {
	Dataset string
	Events  []Event
}

Batch represents Honeycomb events grouped by their target dataset

type Event

type Event struct {
	Attributes map[string]interface{}
	Timestamp  time.Time
	SampleRate int32
}

Event represents a single Honeycomb event

type OTLPError

type OTLPError struct {
	Message        string
	HTTPStatusCode int
	GRPCStatusCode codes.Code
}

func (OTLPError) Error

func (e OTLPError) Error() string

type RequestInfo

type RequestInfo struct {
	ApiKey  string
	Dataset string

	UserAgent          string
	ContentType        string
	ContentEncoding    string
	GRPCAcceptEncoding string
}

RequestInfo represents information parsed from either HTTP headers or gRPC metadata

func GetRequestInfoFromGrpcMetadata

func GetRequestInfoFromGrpcMetadata(ctx context.Context) RequestInfo

GetRequestInfoFromGrpcMetadata parses relevant gRPC metadata from an incoming request context

func GetRequestInfoFromHttpHeaders

func GetRequestInfoFromHttpHeaders(header http.Header) RequestInfo

GetRequestInfoFromHttpHeaders parses relevant incoming HTTP headers

func (*RequestInfo) ValidateLogsHeaders

func (ri *RequestInfo) ValidateLogsHeaders() error

ValidateLogsHeaders validates required headers/metadata for a logs OTLP request

func (*RequestInfo) ValidateMetricsHeaders

func (ri *RequestInfo) ValidateMetricsHeaders() error

ValidateMetricsHeaders validates required headers/metadata for a metric OTLP request

func (*RequestInfo) ValidateTracesHeaders

func (ri *RequestInfo) ValidateTracesHeaders() error

ValidateTracesHeaders validates required headers/metadata for a trace OTLP request

type TranslateOTLPRequestResult

type TranslateOTLPRequestResult struct {
	RequestSize int
	Batches     []Batch
}

TranslateOTLPRequestResult represents an OTLP request translated into Honeycomb-friendly structure RequestSize is total byte size of the entire OTLP request Batches represent events grouped by their target dataset

func TranslateLogsRequest

func TranslateLogsRequest(ctx context.Context, request *collectorLogs.ExportLogsServiceRequest, ri RequestInfo) (*TranslateOTLPRequestResult, error)

TranslateLogsRequest translates an OTLP proto log request into Honeycomb-friendly structure RequestInfo is the parsed information from the gRPC metadata

func TranslateLogsRequestFromReader

func TranslateLogsRequestFromReader(ctx context.Context, body io.ReadCloser, ri RequestInfo) (*TranslateOTLPRequestResult, error)

TranslateLogsRequestFromReader translates an OTLP log request into Honeycomb-friendly structure from a reader (eg HTTP body) RequestInfo is the parsed information from the gRPC metadata

func TranslateTraceRequest

func TranslateTraceRequest(ctx context.Context, request *collectorTrace.ExportTraceServiceRequest, ri RequestInfo) (*TranslateOTLPRequestResult, error)

TranslateTraceRequest translates an OTLP/gRPC request into Honeycomb-friendly structure RequestInfo is the parsed information from the gRPC metadata

func TranslateTraceRequestFromReader

func TranslateTraceRequestFromReader(ctx context.Context, body io.ReadCloser, ri RequestInfo) (*TranslateOTLPRequestResult, error)

TranslateTraceRequestFromReader translates an OTLP/HTTP request into Honeycomb-friendly structure RequestInfo is the parsed information from the HTTP headers