go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/server/bqlog/default.go (about)

     1  // Copyright 2021 The LUCI Authors.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //      http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  package bqlog
    16  
    17  import (
    18  	"context"
    19  
    20  	"google.golang.org/protobuf/proto"
    21  )
    22  
    23  // Default is a bundler installed into the server when using NewModule or
    24  // NewModuleFromFlags.
    25  //
    26  // The module takes care of configuring this bundler based on the server
    27  // environment and module's options.
    28  //
    29  // You still need to register your types in it using RegisterSink.
    30  var Default Bundler
    31  
    32  // RegisterSink tells the bundler where and how to log messages of some
    33  // concrete proto type.
    34  //
    35  // There can currently be only one sink per proto message type. Must be called
    36  // before the bundler is running. Can be called during the init() time.
    37  func RegisterSink(sink Sink) {
    38  	Default.RegisterSink(sink)
    39  }
    40  
    41  // Log asynchronously logs the given message to a BQ table associated with
    42  // the message type via a prior RegisterSink call.
    43  //
    44  // This is a best effort operation (and thus returns no error).
    45  //
    46  // Messages are dropped when:
    47  //   - Writes to BigQuery are failing with a fatal error:
    48  //   - The table doesn't exist.
    49  //   - The table has an incompatible schema.
    50  //   - The server account has no permission to write to the table.
    51  //   - Etc.
    52  //   - The server crashes before it manages to flush buffered logs.
    53  //   - The internal flush buffer is full (per MaxLiveSizeBytes).
    54  //
    55  // In case of transient write errors messages may be duplicated.
    56  //
    57  // Panics if `m` was not registered via RegisterSink or if the bundler is not
    58  // running yet.
    59  func Log(ctx context.Context, m proto.Message) {
    60  	Default.Log(ctx, m)
    61  }