telemetryapi

package
v0.2.0-alpha Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 26, 2022 License: MIT Imports: 9 Imported by: 2

Documentation

Overview

Package telemetryapi implements events receiving HTTP server and decoding function to use Lambda Telemetry API. Implement Processor and use Run function in your main package. For more custom use cases you can use low-level Decode function directly.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func Decode 

func Decode(ctx context.Context, r io.ReadCloser, logs chan<- Event) error

Decode consumes all logs from json array stream and send them to the provided channel. Decode is low-level function. Consider using Run instead and implement Processor. Decode drains and closes the input stream afterwards.

Example 
package main

import (
	"log"
	"net/http"

	"github.com/zakharovvi/aws-lambda-extensions/telemetryapi"
)

func main() {
	// 1. create channel for decoded events
	eventsCh := make(chan telemetryapi.Event)

	// 2. consume decoded events from the channel
	go func() {
		for msg := range eventsCh {
			log.Println(msg.Type)
			log.Println(msg.Time)

			// 3. type cast log records and access fields
			report, ok := msg.Record.(telemetryapi.RecordPlatformReport)
			if !ok {
				continue
			}
			log.Println(report.RequestID)
			log.Println(report.Metrics.BilledDuration)
			log.Println(report.Metrics.MaxMemoryUsedMB)
		}
	}()

	// 4. use Decode in HTTP handler
	http.HandleFunc("/telemetry-receiver", func(w http.ResponseWriter, r *http.Request) {
		if err := telemetryapi.Decode(r.Context(), r.Body, eventsCh); err != nil {
			w.WriteHeader(http.StatusBadRequest)
			log.Println(err)

			return
		}
	})
	log.Panic(http.ListenAndServe("", nil))
}

Output:

func Run 

func Run(ctx context.Context, proc Processor, opts ...Option) error

Run runs the Processor. Run blocks the current goroutine till extension lifecycle is finished or error occurs.

Example 
package main

import (
	"context"
	"log"

	"github.com/zakharovvi/aws-lambda-extensions/extapi"
	"github.com/zakharovvi/aws-lambda-extensions/telemetryapi"
)

type Processor struct{}

func (proc *Processor) Init(ctx context.Context, registerResp *extapi.RegisterResponse) error {
	log.Printf(
		"initializing Processor for function %s(%s), handler %s, and accountID %s\n",
		registerResp.FunctionName,
		registerResp.FunctionVersion,
		registerResp.Handler,
		registerResp.AccountID,
	)

	return nil
}

func (proc *Processor) Process(ctx context.Context, msg telemetryapi.Event) error {
	log.Printf("time=%s type=%s\n", msg.Type, msg.Time)

	return nil
}

func (proc *Processor) Shutdown(ctx context.Context, reason extapi.ShutdownReason, err error) error {
	log.Printf("shutting down extension due to reason=%s error=%v\n", reason, err)

	return nil
}

func main() {
	if err := telemetryapi.Run(context.Background(), &Processor{}); err != nil {
		log.Panic(err)
	}
}

Output:

Types

type Event 

type Event struct {
	// Type property defines the event type.
	Type Type `json:"type"`
	// Time property defines when the Lambda platform generated the event.
	// This isn't the same as when the event actually occurred.
	// The string value of time is a timestamp in ISO 8601 format.
	Time time.Time `json:"time"`
	// RawRecord property defines a JSON object that contains the telemetry data.
	// The schema of this JSON object depends on the type.
	RawRecord json.RawMessage `json:"record"`
	// Record property defines a struct that contains the telemetry data.
	// The type of the struct depends on the Event.Type
	Record any `json:"decodedRecord,omitempty"` // tag for printing the field with json.Marshal
}

Event object that the Lambda Telemetry API supports. After subscribing using the Telemetry API, an extension automatically starts to receive telemetry from Lambda. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-api.html#telemetry-api-messages

type InitReportMetrics 

type InitReportMetrics struct {
	Duration lambdaext.DurationMs `json:"durationMs"`
}

InitReportMetrics contains metrics about an initialization phase. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#InitReportMetrics

type Option 

type Option interface {
	// contains filtered or unexported methods
}

func WithBufferingCfg 

func WithBufferingCfg(bufferingCfg *extapi.TelemetryBufferingCfg) Option

func WithClientOptionsOption 

func WithClientOptionsOption(clientOptions []extapi.Option) Option

func WithDestinationAddr 

func WithDestinationAddr(addr string) Option

WithDestinationAddr configures host and port for telemetry HTTP server to listen Lambda API accepts only "sandbox.localdomain" host.

func WithLogger 

func WithLogger(log logr.Logger) Option

func WithSubscriptionTypes 

func WithSubscriptionTypes(types []extapi.TelemetrySubscriptionType) Option

type Phase 

type Phase string

Phase describes the phase when the initialization step occurs. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#InitPhase 

const (
	// PhaseInit is a Phase when Lambda runs the function initialization in most cases.
	PhaseInit Phase = "init"
	// PhaseInvoke is a Phase when Lambda may re-run the function initialization code during the invoke phase in some error cases. (This is called a suppressed init.)
	PhaseInvoke Phase = "invoke"
)

type Processor 

type Processor interface {
	// Init is called before starting receiving events and Process.
	// It's the best place to make network connections, warmup caches, preallocate buffers, etc.
	Init(ctx context.Context, registerResp *extapi.RegisterResponse) error
	// Process stores events in persistent storage or accumulate in a buffer and flush periodically.
	Process(ctx context.Context, event Event) error
	// Shutdown is called before exiting the extension.
	// Processor should flush all the buffered data to persistent storage if any and cleanup all used resources.
	Shutdown(ctx context.Context, reason extapi.ShutdownReason, err error) error
}

Processor implements client logic to process and store events.

type RecordExtension 

type RecordExtension string

RecordExtension event contains logs from the extension code. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#telemetry-api-extension

type RecordFunction 

type RecordFunction string

RecordFunction event contains logs from the function code. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#telemetry-api-function

type RecordPlatformExtension 

type RecordPlatformExtension struct {
	Name   lambdaext.ExtensionName `json:"name"`
	State  string                  `json:"state"`
	Events []extapi.EventType      `json:"events"`
}

RecordPlatformExtension is generated when an extension registers with the extensions API. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#platform-extension

type RecordPlatformInitReport 

type RecordPlatformInitReport struct {
	InitType lambdaext.InitType `json:"initializationType"`
	Phase    Phase              `json:"phase"`
	Metrics  InitReportMetrics  `json:"metrics"`
}

RecordPlatformInitReport event contains an overall report of the function initialization phase. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#platform-initReport

type RecordPlatformInitRuntimeDone 

type RecordPlatformInitRuntimeDone struct {
	InitType lambdaext.InitType `json:"initializationType"`
	Phase    Phase              `json:"phase"`
	Status   Status             `json:"status"`
	// If the status is either failure or error, then the Status object also contains an errorType field describing the error.
	ErrorType string `json:"errorType"`
}

RecordPlatformInitRuntimeDone event indicates that the function initialization phase has completed. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#platform-initRuntimeDone

type RecordPlatformInitStart 

type RecordPlatformInitStart struct {
	InitType          lambdaext.InitType `json:"initializationType"`
	Phase             Phase              `json:"phase"`
	RuntimeVersion    string             `json:"runtimeVersion,omitempty"`
	RuntimeVersionARN string             `json:"runtimeVersionArn,omitempty"`
}

RecordPlatformInitStart event indicates that the function initialization phase has started. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#platform-initStart

type RecordPlatformLogsDropped 

type RecordPlatformLogsDropped struct {
	DroppedBytes   int    `json:"droppedBytes"`
	DroppedRecords int    `json:"droppedRecords"`
	Reason         string `json:"reason"`
}

RecordPlatformLogsDropped event contains information about dropped events. Lambda emits the platform.logsDropped event when an extension can't process one or more events. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#platform-logsDropped

type RecordPlatformReport 

type RecordPlatformReport struct {
	RequestID lambdaext.RequestID `json:"requestId"`
	Status    Status              `json:"status"`
	Metrics   ReportMetrics       `json:"metrics"`
	Tracing   TraceContext        `json:"tracing,omitempty"`
}

RecordPlatformReport event contains an overall report of the function completed phase. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#platform-report

type RecordPlatformRuntimeDone 

type RecordPlatformRuntimeDone struct {
	RequestID lambdaext.RequestID `json:"requestId"`
	Status    Status              `json:"status"`
	// If the status is either failure or error, then the Status object also contains an errorType field describing the error.
	ErrorType string             `json:"errorType"`
	Metrics   RuntimeDoneMetrics `json:"metrics,omitempty"`
	Tracing   TraceContext       `json:"tracing,omitempty"`
	Spans     []Span             `json:"spans,omitempty"`
}

RecordPlatformRuntimeDone event indicates that the function invocation phase has completed. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#platform-runtimeDone

type RecordPlatformStart 

type RecordPlatformStart struct {
	RequestID lambdaext.RequestID       `json:"requestId"`
	Version   lambdaext.FunctionVersion `json:"version,omitempty"`
	Tracing   TraceContext              `json:"tracing,omitempty"`
}

RecordPlatformStart event indicates that the function invocation phase has started. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#platform-start

type RecordPlatformTelemetrySubscription 

type RecordPlatformTelemetrySubscription struct {
	Name  lambdaext.ExtensionName            `json:"name"`
	State string                             `json:"state"`
	Types []extapi.TelemetrySubscriptionType `json:"types"`
}

RecordPlatformTelemetrySubscription event contains information about an extension subscription. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#platform-telemetrySubscription

type ReportMetrics 

type ReportMetrics struct {
	BilledDuration  lambdaext.DurationMs `json:"billedDurationMs"`
	Duration        lambdaext.DurationMs `json:"durationMs"`
	InitDuration    lambdaext.DurationMs `json:"initDurationMs,omitempty"`
	MaxMemoryUsedMB int                  `json:"maxMemoryUsedMB"`
	MemorySizeMB    int                  `json:"memorySizeMB"`
	RestoreDuration lambdaext.DurationMs `json:"restoreDurationMs,omitempty"`
}

ReportMetrics contains metrics about a completed phase. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#ReportMetrics

type RuntimeDoneMetrics 

type RuntimeDoneMetrics struct {
	Duration      lambdaext.DurationMs `json:"durationMs"`
	ProducedBytes int                  `json:"producedBytes,omitempty"`
}

RuntimeDoneMetrics contains metrics about an invocation phase. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#RuntimeDoneMetrics

type Span 

type Span struct {
	Name     SpanName             `json:"name"`
	Start    time.Time            `json:"start"`
	Duration lambdaext.DurationMs `json:"durationMs"`
}

Span represents a unit of work or operation in a trace. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#Span

type SpanName 

type SpanName string
const (
	// SpanResponseLatency span describes how long it took your Lambda function to start sending the response.
	SpanResponseLatency SpanName = "responseLatency"
	// SpanResponseDuration span describes how long it took your Lambda function to finish sending the entire response.
	SpanResponseDuration SpanName = "responseDuration"
)

type Status 

type Status string

Status describes the status of an initialization or invocation phase. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#Status 

const (
	StatusSuccess Status = "success"
	StatusFailure Status = "failure"
	StatusError   Status = "error"
)

type TraceContext 

type TraceContext struct {
	SpanID string                 `json:"spanId,omitempty"`
	Type   lambdaext.TracingType  `json:"type"`
	Value  lambdaext.TracingValue `json:"value"`
}

TraceContext describes the properties of a trace. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html#TraceContext

type Type 

type Type string

Type details the types of Event objects that the Lambda Telemetry API supports. https://docs.aws.amazon.com/lambda/latest/dg/telemetry-schema-reference.html 

const (
	// TypePlatformInitStart event is emitted when function initialization started.
	TypePlatformInitStart Type = "platform.initStart"
	// TypePlatformInitRuntimeDone event is emitted when function initialization completed.
	TypePlatformInitRuntimeDone Type = "platform.initRuntimeDone"
	// TypePlatformInitReport event is a report of function initialization.
	TypePlatformInitReport Type = "platform.initReport"
	// TypePlatformStart event is emitted when function invocation started.
	TypePlatformStart Type = "platform.start"
	// TypePlatformRuntimeDone event is emitted when the runtime finished processing an event with either success or failure.
	TypePlatformRuntimeDone Type = "platform.runtimeDone"
	// TypePlatformReport event is a report of function invocation.
	TypePlatformReport Type = "platform.report"
	// TypePlatformExtension event is emitted when an extension registers with the extensions API.
	TypePlatformExtension = "platform.extension"
	// TypePlatformTelemetrySubscription event is emitted when an extension subscribed to the Telemetry API.
	TypePlatformTelemetrySubscription Type = "platform.telemetrySubscription"
	// TypePlatformLogsDropped event is mmited when lambda dropped log entries.
	TypePlatformLogsDropped Type = "platform.logsDropped"
	// TypeFunction event is a log line from function code.
	TypeFunction Type = "function"
	// TypeExtension event is a log line from extension code.
	TypeExtension Type = "extension"
)

Source Files

View all Source files

Directories

Path Synopsis
Package otel implements conversion from Telemetry API events into OpenTelemetry trace spans.
 Package otel implements conversion from Telemetry API events into OpenTelemetry trace spans.
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.