modulepackage
0.75.0
Repository: https://github.com/einride/cloudrunner-go.git
Documentation: pkg.go.dev
# README
Cloud Runner
Get up and running with Go and gRPC on Google Cloud Platform, with this lightweight, opinionated, batteries-included service SDK.
Features
Run your application with cloudrunner.Run, and you get:
- Logging integrated with Cloud Logging using Zap.
- Tracing integrated with Cloud Trace usingOpenTelemetry Go.
- Metrics integrated with Cloud Monitoring usingOpenTelemetry Go.
- Profiling integrated with Cloud Profiler using the Google Cloud Go SDK.
To help you build gRPC microservices, you also get:
- Server-to-server authentication, client retries, and more for gRPC clients
with
cloudrunner.DialService. - Request logging, tracing, and more, for gRPC servers
with
cloudrunner.NewGRPCServer.
Get up and running
Install the package:
$ go get go.einride.tech/cloudrunner
Try out a minimal example:
package main
import (
"context"
"log"
"go.einride.tech/cloudrunner"
"google.golang.org/grpc/health"
"google.golang.org/grpc/health/grpc_health_v1"
)
func main() {
if err := cloudrunner.Run(func(ctx context.Context) error {
cloudrunner.Logger(ctx).Info("hello world")
grpcServer := cloudrunner.NewGRPCServer(ctx)
healthServer := health.NewServer()
grpc_health_v1.RegisterHealthServer(grpcServer, healthServer)
return cloudrunner.ListenGRPC(ctx, grpcServer)
}); err != nil {
log.Fatal(err)
}
}
Configuration
The service is configured with environment variables.
When the service is running on GCE, all built-in integrations are turned on by default.
Service-specific config is supported out of the box.
Invoke your service with -help to show available configuration.
Usage of grpc-server:
-config string
load environment from a YAML service specification
-help
show help then exit
-validate
validate config then exit
Runtime configuration of grpc-server:
CONFIG ENV TYPE DEFAULT ON GCE
cloudrunner PORT int 8080
cloudrunner K_SERVICE string
cloudrunner K_REVISION string
cloudrunner K_CONFIGURATION string
cloudrunner CLOUD_RUN_JOB string
cloudrunner CLOUD_RUN_EXECUTION string
cloudrunner CLOUD_RUN_TASK_INDEX int
cloudrunner CLOUD_RUN_TASK_ATTEMPT int
cloudrunner CLOUD_RUN_TASK_COUNT int
cloudrunner GOOGLE_CLOUD_PROJECT string
cloudrunner RUNTIME_SERVICEACCOUNT string
cloudrunner SERVICE_VERSION string
cloudrunner LOGGER_DEVELOPMENT bool true false
cloudrunner LOGGER_LEVEL zapcore.Level debug info
cloudrunner LOGGER_REPORTERRORS bool true
cloudrunner PROFILER_ENABLED bool true
cloudrunner PROFILER_MUTEXPROFILING bool
cloudrunner PROFILER_ALLOCFORCEGC bool true
cloudrunner TRACEEXPORTER_ENABLED bool true
cloudrunner TRACEEXPORTER_TIMEOUT time.Duration 10s
cloudrunner TRACEEXPORTER_SAMPLEPROBABILITY float64 0.01
cloudrunner METRICEXPORTER_ENABLED bool false
cloudrunner METRICEXPORTER_INTERVAL time.Duration 60s
cloudrunner METRICEXPORTER_RUNTIMEINSTRUMENTATION bool true
cloudrunner METRICEXPORTER_HOSTINSTRUMENTATION bool true
cloudrunner METRICEXPORTER_OPENCENSUSPRODUCER bool false
cloudrunner SERVER_TIMEOUT time.Duration 290s
cloudrunner CLIENT_TIMEOUT time.Duration 10s
cloudrunner CLIENT_RETRY_ENABLED bool true
cloudrunner CLIENT_RETRY_INITIALBACKOFF time.Duration 200ms
cloudrunner CLIENT_RETRY_MAXBACKOFF time.Duration 60s
cloudrunner CLIENT_RETRY_MAXATTEMPTS int 5
cloudrunner CLIENT_RETRY_BACKOFFMULTIPLIER float64 2
cloudrunner CLIENT_RETRY_RETRYABLESTATUSCODES []codes.Code Unavailable,Unknown
cloudrunner REQUESTLOGGER_MESSAGESIZELIMIT int 1024
cloudrunner REQUESTLOGGER_CODETOLEVEL map[codes.Code]zapcore.Level
cloudrunner REQUESTLOGGER_STATUSTOLEVEL map[int]zapcore.Level
Build-time configuration of grpc-server:
LDFLAG TYPE VALUE
go.einride.tech/cloudrunner/cloudruntime.serviceVersion string
# Packages
Package cloudclient provides primitives for gRPC clients.
Package cloudconfig provides primitives for loading configuration.
No description provided by the author
No description provided by the author
Package cloudotel provides primitives for OpenTelemetry.
Package cloudprofiler provides primitives for Cloud Profiler integration.
No description provided by the author
Package cloudrequestlog contains primitives for request logging.
Package cloudruntime provides primitives for loading data from the cloud runtime.
Package cloudserver provides primitives for gRPC and HTTP servers.
Package cloudslog provides primitives for structured logging with the standard library log/slog package.
No description provided by the author
No description provided by the author
Package cloudtesting provides testing utilities.
Package cloudtrace provides primitives for Cloud Trace integration.
Package cloudzap provides primitives for structured logging with go.uber.org/zap.
No description provided by the author
# Functions
AddRequestLogFields adds fields to the current request log, and is safe to call concurrently.
AddRequestLogFieldsToArray appends objects to an array field in the request log and is safe to call concurrently.
DialService dials another service using the default service account's Google ID Token authentication.
GetTraceContext returns the Cloud Trace context from the incoming request.
IncomingTraceContext returns the Cloud Trace context from the incoming request metadata.
ListenGRPC binds a listener on the configured port and listens for gRPC requests.
ListenGRPCHTTP binds a listener on the configured port and listens for gRPC and HTTP requests.
ListenHTTP binds a listener on the configured port and listens for HTTP requests.
Logger returns the logger for the current context.
NewGRPCServer creates a new gRPC server preconfigured with middleware for request logging, tracing, etc.
NewHTTPServer creates a new HTTP server preconfigured with middleware for request logging, tracing, etc.
PubsubHTTPHandler creates a new HTTP handler for Cloud Pub/Sub push messages.
Run a service.
Runtime returns the runtime config for the current context.
WithConfig configures an additional config struct to be loaded.
WithGRPCServerOptions configures the run context with additional default options for NewGRPCServer.
WithLoggerFields attaches structured fields to a new logger in the returned child context.
WithOptions configures the run context with a list of options.
WithRequestLoggerMessageTransformer configures the request logger with a message transformer.
WithTraceHook configures the run context with a trace hook.
Wrap an error with a gRPC status.
WrapTransient wraps transient errors (possibly status.Status) with appropriate codes.Code.
# Type aliases
HTTPMiddleware is an HTTP middleware.
Option provides optional configuration for a run context.