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]slog.Level
cloudrunner REQUESTLOGGER_STATUSTOLEVEL map[int]slog.Level
Build-time configuration of grpc-server:
LDFLAG TYPE VALUE
go.einride.tech/cloudrunner/cloudruntime.serviceVersion string
Documentation
¶
Overview ¶
Package cloudrunner provides primitives for getting up and running with Go on Google Cloud.
Index ¶
- func AddRequestLogFields(ctx context.Context, args ...any)
- func AddRequestLogFieldsToArray(ctx context.Context, key string, objects ...any)
- func DialService(ctx context.Context, target string, opts ...grpc.DialOption) (*grpc.ClientConn, error)
- func GetTraceContext(ctx context.Context) (cloudtrace.Context, bool)
- func IncomingTraceContext(ctx context.Context) (cloudtrace.Context, bool)
- func ListenGRPC(ctx context.Context, grpcServer *grpc.Server) error
- func ListenGRPCHTTP(ctx context.Context, grpcServer *grpc.Server, httpServer *http.Server) error
- func ListenHTTP(ctx context.Context, httpServer *http.Server) error
- func Logger(ctx context.Context) *zap.Logger
- func NewGRPCServer(ctx context.Context, opts ...grpc.ServerOption) *grpc.Server
- func NewHTTPServer(ctx context.Context, handler http.Handler, middlewares ...HTTPMiddleware) *http.Server
- func PubsubHTTPHandler(fn func(context.Context, *pubsubpb.PubsubMessage) error) http.Handler
- func Run(fn func(context.Context) error, options ...Option) (err error)
- func Runtime(ctx context.Context) cloudruntime.Config
- func WithLoggerFields(ctx context.Context, fields ...zap.Field) context.Context
- func Wrap(err error, s *status.Status) error
- func WrapTransient(err error, msg string) error
- type HTTPMiddleware
- type Option
- func WithConfig(name string, config interface{}) Option
- func WithGRPCServerOptions(grpcServerOptions ...grpc.ServerOption) Option
- func WithOptions(options []Option) Option
- func WithRequestLoggerMessageTransformer(func(proto.Message) proto.Message) Option
- func WithTraceHook(traceHook func(context.Context, cloudtrace.Context) context.Context) Option
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddRequestLogFields ¶
AddRequestLogFields adds fields to the current request log, and is safe to call concurrently.
func AddRequestLogFieldsToArray ¶
AddRequestLogFieldsToArray appends objects to an array field in the request log and is safe to call concurrently.
func DialService ¶
func DialService(ctx context.Context, target string, opts ...grpc.DialOption) (*grpc.ClientConn, error)
DialService dials another service using the default service account's Google ID Token authentication.
func GetTraceContext ¶ added in v0.30.0
func GetTraceContext(ctx context.Context) (cloudtrace.Context, bool)
GetTraceContext returns the Cloud Trace context from the incoming request.
func IncomingTraceContext ¶
func IncomingTraceContext(ctx context.Context) (cloudtrace.Context, bool)
IncomingTraceContext returns the Cloud Trace context from the incoming request metadata. Deprecated: Use GetTraceContext instead.
func ListenGRPC ¶
ListenGRPC binds a listener on the configured port and listens for gRPC requests.
func ListenGRPCHTTP ¶ added in v0.22.0
ListenGRPCHTTP binds a listener on the configured port and listens for gRPC and HTTP requests.
func ListenHTTP ¶
ListenHTTP binds a listener on the configured port and listens for HTTP requests.
func NewGRPCServer ¶
NewGRPCServer creates a new gRPC server preconfigured with middleware for request logging, tracing, etc.
func NewHTTPServer ¶
func NewHTTPServer(ctx context.Context, handler http.Handler, middlewares ...HTTPMiddleware) *http.Server
NewHTTPServer creates a new HTTP server preconfigured with middleware for request logging, tracing, etc.
func PubsubHTTPHandler ¶
PubsubHTTPHandler creates a new HTTP handler for Cloud Pub/Sub push messages. See: https://cloud.google.com/pubsub/docs/push
func Run ¶
Run a service. Configuration of the service is loaded from the environment.
Example (GRPCServer) ¶
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 {
grpcServer := cloudrunner.NewGRPCServer(ctx)
healthServer := health.NewServer()
grpc_health_v1.RegisterHealthServer(grpcServer, healthServer)
return cloudrunner.ListenGRPC(ctx, grpcServer)
}); err != nil {
log.Fatal(err)
}
}
Output:
Example (HelloWorld) ¶
package main
import (
"context"
"log"
"go.einride.tech/cloudrunner"
)
func main() {
if err := cloudrunner.Run(func(ctx context.Context) error {
cloudrunner.Logger(ctx).Info("hello world")
return nil
}); err != nil {
log.Fatal(err)
}
}
Output:
func Runtime ¶
func Runtime(ctx context.Context) cloudruntime.Config
Runtime returns the runtime config for the current context.
func WithLoggerFields ¶
WithLoggerFields attaches structured fields to a new logger in the returned child context.
func WrapTransient ¶
WrapTransient wraps transient errors (possibly status.Status) with appropriate codes.Code. The returned error will always be a status.Status with description set to msg.
Types ¶
type HTTPMiddleware ¶
HTTPMiddleware is an HTTP middleware.
type Option ¶
type Option func(*runContext)
Option provides optional configuration for a run context.
func WithConfig ¶
WithConfig configures an additional config struct to be loaded.
func WithGRPCServerOptions ¶
func WithGRPCServerOptions(grpcServerOptions ...grpc.ServerOption) Option
WithGRPCServerOptions configures the run context with additional default options for NewGRPCServer.
func WithOptions ¶
WithOptions configures the run context with a list of options.
func WithRequestLoggerMessageTransformer ¶
WithRequestLoggerMessageTransformer configures the request logger with a message transformer. Deprecated: This was historically used for redaction. All proto messages are now automatically redacted.
func WithTraceHook ¶ added in v0.10.0
WithTraceHook configures the run context with a trace hook.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cloudclient provides primitives for gRPC clients.
|
Package cloudclient provides primitives for gRPC clients. |
|
Package cloudconfig provides primitives for loading configuration.
|
Package cloudconfig provides primitives for loading configuration. |
|
Package cloudotel provides primitives for OpenTelemetry.
|
Package cloudotel provides primitives for OpenTelemetry. |
|
Package cloudprofiler provides primitives for Cloud Profiler integration.
|
Package cloudprofiler provides primitives for Cloud Profiler integration. |
|
Package cloudrequestlog contains primitives for request logging.
|
Package cloudrequestlog contains primitives for request logging. |
|
Package cloudruntime provides primitives for loading data from the cloud runtime.
|
Package cloudruntime provides primitives for loading data from the cloud runtime. |
|
Package cloudserver provides primitives for gRPC and HTTP servers.
|
Package cloudserver provides primitives for gRPC and HTTP servers. |
|
Package cloudslog provides primitives for structured logging with the standard library log/slog package.
|
Package cloudslog provides primitives for structured logging with the standard library log/slog package. |
|
Package cloudtesting provides testing utilities.
|
Package cloudtesting provides testing utilities. |
|
Package cloudtrace provides primitives for Cloud Trace integration.
|
Package cloudtrace provides primitives for Cloud Trace integration. |
|
Package cloudzap provides primitives for structured logging with go.uber.org/zap.
|
Package cloudzap provides primitives for structured logging with go.uber.org/zap. |
|
examples
|
|