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 Wrap ¶
Wrap masks the gRPC status of the provided error by replacing it with the provided status.
func WrapTransient ¶
WrapTransient masks the gRPC status of the provided error by replacing the status message. If the original error has transient (retryable) gRPC status code, the status code will be forwarded. Otherwise, the status code will be masked with INTERNAL.
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
|
|