Skip to content

Commit

Permalink
docs: document how to enable logging (#11298)
Browse files Browse the repository at this point in the history
  • Loading branch information
@codyoss
codyoss authored Dec 17, 2024
1 parent 6cf33a8 commit 9724361
Showing 1 changed file with 11 additions and 128 deletions.
139 changes: 11 additions & 128 deletions debug.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,17 @@ impact and are therefore not recommended for sustained production use. Use these
tips locally or in production for a *limited time* to help get a better
understanding of what is going on.

### Request/Response Logging

To enable logging for all outgoing requests from the Go Client Libraries, set
the environment variable `GOOGLE_SDK_GO_LOGGING_LEVEL` to `debug`. Currently all
logging is at the debug level, but this is likely to change in the future.

*Caution*: Debug level logging should only be used in a limited manner. Debug
level logs contain sensitive information, including headers, request/response
payloads, and authentication tokens. Additionally, enabling logging at this
level will have a minor performance impact.

### HTTP based clients

All of our auto-generated clients have a constructor to create a client that
Expand All @@ -40,74 +51,6 @@ GODEBUG=http2debug=1. To read more about this feature please see the godoc for
*WARNING*: Enabling this debug variable will log headers and payloads which may
contain private information.

#### Add in your own logging with an HTTP middleware

You may want to add in your own logging around HTTP requests. One way to do this
is to register a custom HTTP client with a logging transport built in. Here is
an example of how you would do this with the storage client.

*WARNING*: Adding this middleware will log headers and payloads which may
contain private information.

```go
package main

import (
"context"
"fmt"
"log"
"net/http"
"net/http/httputil"

"cloud.google.com/go/storage"
"google.golang.org/api/iterator"
"google.golang.org/api/option"
htransport "google.golang.org/api/transport/http"
)

type loggingRoundTripper struct {
rt http.RoundTripper
}

func (d loggingRoundTripper) RoundTrip(r *http.Request) (*http.Response, error) {
// Will create a dump of the request and body.
dump, err := httputil.DumpRequest(r, true)
if err != nil {
log.Println("error dumping request")
}
log.Printf("%s", dump)
return d.rt.RoundTrip(r)
}

func main() {
ctx := context.Background()

// Create a transport with authentication built-in detected with
// [ADC](https://google.aip.dev/auth/4110). Note you will have to pass any
// required scoped for the client you are using.
trans, err := htransport.NewTransport(ctx,
http.DefaultTransport,
option.WithScopes(storage.ScopeFullControl),
)
if err != nil {
log.Fatal(err)
}

// Embed customized transport into an HTTP client.
hc := &http.Client{
Transport: loggingRoundTripper{rt: trans},
}

// Supply custom HTTP client for use by the library.
client, err := storage.NewClient(ctx, option.WithHTTPClient(hc))
if err != nil {
log.Fatal(err)
}
defer client.Close()
// Use the client
}
```

### gRPC based clients

#### Try setting grpc-go's debug variables
Expand All @@ -117,66 +60,6 @@ Try setting the following environment variables for grpc-go:
good for diagnosing connection level failures. For more information please see
[grpc-go's debug documentation](https://pkg.go.dev/google.golang.org/grpc/examples/features/debugging#section-readme).

#### Add in your own logging with a gRPC interceptors

You may want to add in your own logging around gRPC requests. One way to do this
is to register a custom interceptor that adds logging. Here is
an example of how you would do this with the secretmanager client. Note this
example registers a UnaryClientInterceptor but you may want/need to register
a StreamClientInterceptor instead-of/as-well depending on what kinds of
RPCs you are calling.

*WARNING*: Adding this interceptor will log metadata and payloads which may
contain private information.

```go
package main

import (
"context"
"log"

secretmanager "cloud.google.com/go/secretmanager/apiv1"
"google.golang.org/api/option"
"google.golang.org/grpc"
"google.golang.org/grpc/metadata"
"google.golang.org/protobuf/encoding/protojson"
"google.golang.org/protobuf/reflect/protoreflect"
)

func loggingUnaryInterceptor() grpc.UnaryClientInterceptor {
return func(ctx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
err := invoker(ctx, method, req, reply, cc, opts...)
log.Printf("Invoked method: %v", method)
md, ok := metadata.FromOutgoingContext(ctx)
if ok {
log.Println("Metadata:")
for k, v := range md {
log.Printf("Key: %v, Value: %v", k, v)
}
}
reqb, merr := protojson.Marshal(req.(protoreflect.ProtoMessage))
if merr == nil {
log.Printf("Request: %s", reqb)
}
return err
}
}

func main() {
ctx := context.Background()
// Supply custom gRPC interceptor for use by the client.
client, err := secretmanager.NewClient(ctx,
option.WithGRPCDialOption(grpc.WithUnaryInterceptor(loggingUnaryInterceptor())),
)
if err != nil {
log.Fatal(err)
}
defer client.Close()
// Use the client
}
```

## Telemetry

**Warning: The OpenCensus project is obsolete and was archived on July 31st,
Expand Down

0 comments on commit 9724361

Please sign in to comment.