logsapi

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

README

Lambda Logs API

Warning The Lambda Telemetry API supersedes the Lambda Logs API. While the Logs API remains fully functional, we recommend using only the Telemetry API going forward. You can subscribe your extension to a telemetry stream using either the Telemetry API or the Logs API. After subscribing using one of these APIs, any attempt to subscribe using the other API returns an error.

Documentation

Overview

Package logsapi implements logs receiving HTTP server and decoding function to use Lambda Logs API. Implement Processor and use Run function in your main package. For more custom use cases you can use low-level DecodeLogs function directly.

Deprecated: The Lambda Telemetry API supersedes the Lambda Logs API. While the Logs API remains fully functional, we recommend using only the Telemetry API going forward. Use telemetryapi.Run instead. https://docs.aws.amazon.com/lambda/latest/dg/runtimes-logs-api.html https://aws.amazon.com/blogs/compute/introducing-the-aws-lambda-telemetry-api/

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func DecodeLogs 

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

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

Example 
package main

import (
	"log"
	"net/http"

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

func main() {
	// 1. create channel for decoded logs
	logsCh := make(chan logsapi.Log)

	// 2. consume decoded logs from the channel
	go func() {
		for msg := range logsCh {
			log.Println(msg.LogType)
			log.Println(msg.Time)

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

	// 4. use DecodeLogs in HTTP handler
	http.HandleFunc("/logs-receiver", func(w http.ResponseWriter, r *http.Request) {
		if err := logsapi.DecodeLogs(r.Context(), r.Body, logsCh); 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/logsapi"
)

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 logsapi.Log) error {
	log.Printf("time=%s type=%s\n", msg.LogType, 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 := logsapi.Run(context.Background(), &Processor{}); err != nil {
		log.Panic(err)
	}
}

Output:

Types

type Log 

type Log struct {
	// Type property defines the event type.
	// The following table describes all possible values.
	LogType LogType `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 Log.LogType
	Record any `json:"decodedRecord,omitempty"` // tag for printing the field with json.Marshal
}

Log is a parsed log record from Lambda Logs API. Use type assertion for Log.Record field to access custom fields of current Log.LogType.

type LogType 

type LogType string

LogType represents the type of logs received from Lambda Logs API. 

const (
	// LogPlatformStart is the invocation start time.
	LogPlatformStart LogType = "platform.start"
	// LogPlatformEnd is the invocation end time.
	LogPlatformEnd LogType = "platform.end"
	// LogPlatformReport includes metrics about the invocation that the lambdaext.RequestID specifies.
	LogPlatformReport LogType = "platform.report"
	// LogPlatformExtension is generated when an extension registers with the extensions API.
	LogPlatformExtension LogType = "platform.extension"
	// LogPlatformLogsSubscription is generated when an extension subscribes to the logs API.
	LogPlatformLogsSubscription LogType = "platform.logsSubscription"
	// LogPlatformLogsDropped is generated when an extension is not able to process the number of logs that it is receiving.
	LogPlatformLogsDropped LogType = "platform.logsDropped"
	// LogPlatformFault log captures runtime or execution environment errors.
	LogPlatformFault LogType = "platform.fault"
	// LogPlatformRuntimeDone is generated after the function invocation completes either successfully or with an error.
	// The extension can use this message to stop all the telemetry collection for this function invocation.
	// Lambda sends the platform.runtimeDone message after the runtime sends the NEXT request when the function invocation completes.
	LogPlatformRuntimeDone LogType = "platform.runtimeDone"
	// LogFunction logs are generated by the lambda function and internal extensions and written to stdout or stderr.
	LogFunction LogType = "function"
	// LogExtension logs are generated by extensions and written to stdout or stderr.
	LogExtension LogType = "extension"
)

type Metrics 

type Metrics struct {
	Duration       lambdaext.DurationMs `json:"durationMs"`
	BilledDuration lambdaext.DurationMs `json:"billedDurationMs"`
	// InitDuration field is included in the log only if the invocation included a cold start.
	InitDuration    lambdaext.DurationMs `json:"initDurationMs"`
	MemorySizeMB    uint64               `json:"memorySizeMB"`
	MaxMemoryUsedMB uint64               `json:"maxMemoryUsedMB"`
}

type Option 

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

func WithBufferingCfg 

func WithBufferingCfg(bufferingCfg *extapi.LogsBufferingCfg) Option

func WithClientOptionsOption 

func WithClientOptionsOption(clientOptions []extapi.Option) Option

func WithDestinationAddr 

func WithDestinationAddr(addr string) Option

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

func WithLogTypes 

func WithLogTypes(types []extapi.LogSubscriptionType) Option

func WithLogger 

func WithLogger(log logr.Logger) Option

type Processor 

type Processor interface {
	// Init is called before starting receiving logs 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 log message in persistent storage or accumulate in a buffer and flush periodically.
	Process(ctx context.Context, event Log) 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 log messages.

type RecordExtension 

type RecordExtension string

RecordExtension logs are generated by extensions and written to stdout or stderr.

type RecordFunction 

type RecordFunction string

RecordFunction logs are generated by the lambda function and internal extensions and written to stdout or stderr.

type RecordPlatformEnd 

type RecordPlatformEnd struct {
	RequestID lambdaext.RequestID `json:"requestId"`
}

RecordPlatformEnd is the invocation end time.

type RecordPlatformExtension 

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

RecordPlatformExtension is generated when an extension registers with the extensions API.

type RecordPlatformFault 

type RecordPlatformFault string

RecordPlatformFault log captures runtime or execution environment errors.

type RecordPlatformLogsDropped 

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

RecordPlatformLogsDropped is generated when an extension is not able to process the number of logs that it is receiving.

type RecordPlatformLogsSubscription 

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

RecordPlatformLogsSubscription is generated when an extension subscribes to the logs API.

type RecordPlatformReport 

type RecordPlatformReport struct {
	Metrics   Metrics             `json:"metrics"`
	RequestID lambdaext.RequestID `json:"requestId"`
	// Tracing field is included if AWS X-Ray tracing is active, the log includes X-Ray metadata.
	Tracing extapi.Tracing `json:"tracing,omitempty"`
}

RecordPlatformReport includes metrics about the invocation that the lambdaext.RequestID specifies.

type RecordPlatformRuntimeDone 

type RecordPlatformRuntimeDone struct {
	RequestID lambdaext.RequestID `json:"requestId"`
	Status    RuntimeDoneStatus   `json:"status"`
}

RecordPlatformRuntimeDone is generated after the function invocation completes either successfully or with an error. The extension can use this message to stop all the telemetry collection for this function invocation. Lambda sends the platform.runtimeDone message after the runtime sends the NEXT request when the function invocation completes.

type RecordPlatformStart 

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

RecordPlatformStart is the invocation start time.

type RuntimeDoneStatus 

type RuntimeDoneStatus string
const (
	RuntimeDoneSuccess RuntimeDoneStatus = "success"
	RuntimeDoneFailure RuntimeDoneStatus = "failure"
	RuntimeDoneTimeout RuntimeDoneStatus = "timeout"
)

Source Files

View all Source files

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.