package binarylog

Import Path
	google.golang.org/grpc/internal/binarylog (on go.dev)

Dependency Relation
	imports 20 packages, and imported by one package

Involved Source Files

	   #d binarylog.go
		Package binarylog implementation binary logging as defined in
		https://github.com/grpc/proposal/blob/master/A16-binary-logging.md.

	      binarylog_testutil.go
	      env_config.go
	      method_logger.go
	      sink.go
Package-Level Type Names (total 19, in which 14 are exported)

	/* sort exporteds by: alphabet | popularity */
	 type Cancel (struct)
		Cancel configs the binary log entry to be a Cancel entry.

		Fields (only one, which is exported)
			OnClientSide bool
		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*Cancel) toProto() *binlogpb.GrpcLogEntry
		Implements (at least one exported)
			*Cancel : LogEntryConfig

	 type ClientHalfClose (struct)
		ClientHalfClose configs the binary log entry to be a ClientHalfClose entry.

		Fields (only one, which is exported)
			OnClientSide bool
		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*ClientHalfClose) toProto() *binlogpb.GrpcLogEntry
		Implements (at least one exported)
			*ClientHalfClose : LogEntryConfig

	 type ClientHeader (struct)
		ClientHeader configs the binary log entry to be a ClientHeader entry.

		Fields (total 6, all are exported)
			Authority string
			Header metadata.MD
			MethodName string
			OnClientSide bool
			PeerAddr net.Addr
				PeerAddr is required only when it's on server side.

			Timeout time.Duration
		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*ClientHeader) toProto() *binlogpb.GrpcLogEntry
		Implements (at least one exported)
			*ClientHeader : LogEntryConfig

	 type ClientMessage (struct)
		ClientMessage configs the binary log entry to be a ClientMessage entry.

		Fields (total 2, both are exported)
			Message interface{}
				Message can be a proto.Message or []byte. Other messages formats are not
				supported.

			OnClientSide bool
		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*ClientMessage) toProto() *binlogpb.GrpcLogEntry
		Implements (at least one exported)
			*ClientMessage : LogEntryConfig

	 type LogEntryConfig (interface)
		LogEntryConfig represents the configuration for binary log entry.

		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			( LogEntryConfig) toProto() *binlogpb.GrpcLogEntry
		Implemented By (at least 7, all are exported)
			*Cancel
			*ClientHalfClose
			*ClientHeader
			*ClientMessage
			*ServerHeader
			*ServerMessage
			*ServerTrailer
		As Inputs Of (at least 3, all are exported)
			func MethodLogger.Log(LogEntryConfig)
			func (*TruncatingMethodLogger).Build(c LogEntryConfig) *binlogpb.GrpcLogEntry
			func (*TruncatingMethodLogger).Log(c LogEntryConfig)

	 type Logger (interface)
		Logger is the global binary logger. It can be used to get binary logger for
		each method.

		Methods (only one, which is exported)
			( Logger) GetMethodLogger(methodName string) MethodLogger
		Implemented By (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			*logger
		As Outputs Of (at least 3, all are exported)
			func GetLogger() Logger
			func NewLoggerFromConfig(config LoggerConfig) Logger
			func NewLoggerFromConfigString(s string) Logger
		As Inputs Of (at least 3, in which 1 are exported)
			func SetLogger(l Logger)
			/* 2+ unexporteds ... *//* 2+ unexporteds: */
			func google.golang.org/grpc.binaryLogger(bl Logger) grpc.ServerOption
			func google.golang.org/grpc.withBinaryLogger(bl Logger) grpc.DialOption
		As Types Of (total 2, in which 1 are exported)
			  var AllLogger
			/* one unexported ... *//* one unexported: */
			  var binLogger

	 type LoggerConfig (struct)
		LoggerConfig contains the config for loggers to create method loggers.

		Fields (total 4, all are exported)
			All *MethodLoggerConfig
			Blacklist map[string]struct{}
			Methods map[string]*MethodLoggerConfig
			Services map[string]*MethodLoggerConfig
		As Inputs Of (at least one exported)
			func NewLoggerFromConfig(config LoggerConfig) Logger

	 type MethodLogger (interface)
		MethodLogger is the sub-logger for each method.

		Methods (only one, which is exported)
			( MethodLogger) Log(LogEntryConfig)
		Implemented By (at least one exported)
			*TruncatingMethodLogger
		As Outputs Of (at least 2, both are exported)
			func GetMethodLogger(methodName string) MethodLogger
			func Logger.GetMethodLogger(methodName string) MethodLogger

	 type MethodLoggerConfig (struct)
		MethodLoggerConfig contains the setting for logging behavior of a method
		logger. Currently, it contains the max length of header and message.

		Fields (total 2, both are exported)
			Header uint64
				Max length of header and message.

			Message uint64
				Max length of header and message.


	 type ServerHeader (struct)
		ServerHeader configs the binary log entry to be a ServerHeader entry.

		Fields (total 3, all are exported)
			Header metadata.MD
			OnClientSide bool
			PeerAddr net.Addr
				PeerAddr is required only when it's on client side.

		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*ServerHeader) toProto() *binlogpb.GrpcLogEntry
		Implements (at least one exported)
			*ServerHeader : LogEntryConfig

	 type ServerMessage (struct)
		ServerMessage configs the binary log entry to be a ServerMessage entry.

		Fields (total 2, both are exported)
			Message interface{}
				Message can be a proto.Message or []byte. Other messages formats are not
				supported.

			OnClientSide bool
		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*ServerMessage) toProto() *binlogpb.GrpcLogEntry
		Implements (at least one exported)
			*ServerMessage : LogEntryConfig

	 type ServerTrailer (struct)
		ServerTrailer configs the binary log entry to be a ServerTrailer entry.

		Fields (total 4, all are exported)
			Err error
				Err is the status error.

			OnClientSide bool
			PeerAddr net.Addr
				PeerAddr is required only when it's on client side and the RPC is trailer
				only.

			Trailer metadata.MD
		Methods (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			(*ServerTrailer) toProto() *binlogpb.GrpcLogEntry
		Implements (at least one exported)
			*ServerTrailer : LogEntryConfig

	 type Sink (interface)
		Sink writes log entry into the binary log sink.

		sink is a copy of the exported binarylog.Sink, to avoid circular dependency.

		Methods (total 2, both are exported)
			( Sink) Close() error
				Close will be called when the Sink is replaced by a new Sink.

			( Sink) Write(*binlogpb.GrpcLogEntry) error
				Write will be called to write the log entry into the sink.

				It should be thread-safe so it can be called in parallel.

		Implemented By (at least 3, none are exported)
			/* 3+ unexporteds ... *//* 3+ unexporteds: */
			*bufferedSink
			*noopSink
			*writerSink
		Implements (at least one exported)
			 Sink : io.Closer
		As Outputs Of (at least 2, in which 1 are exported)
			func NewBufferedSink(o io.WriteCloser) Sink
			/* at least one unexported ... *//* at least one unexported: */
			func newWriterSink(w io.Writer) Sink
		As Types Of (only one, which is exported)
			  var DefaultSink

	 type TruncatingMethodLogger (struct)
		TruncatingMethodLogger is a method logger that truncates headers and messages
		based on configured fields.

		Fields (total 5, none are exported)
			/* 5 unexporteds ... *//* 5 unexporteds: */
			callID uint64
			headerMaxLen uint64
			idWithinCallGen *callIDGenerator
			messageMaxLen uint64
			sink Sink
				// TODO(blog): make this plugable.

		Methods (total 4, in which 2 are exported)
			(*TruncatingMethodLogger) Build(c LogEntryConfig) *binlogpb.GrpcLogEntry
				Build is an internal only method for building the proto message out of the
				input event. It's made public to enable other library to reuse as much logic
				in TruncatingMethodLogger as possible.

			(*TruncatingMethodLogger) Log(c LogEntryConfig)
				Log creates a proto binary log entry, and logs it to the sink.

			/* 2 unexporteds ... *//* 2 unexporteds: */
			(*TruncatingMethodLogger) truncateMessage(msgPb *binlogpb.Message) (truncated bool)
			(*TruncatingMethodLogger) truncateMetadata(mdPb *binlogpb.Metadata) (truncated bool)
		Implements (at least one exported)
			*TruncatingMethodLogger : MethodLogger
		As Outputs Of (at least one exported)
			func NewTruncatingMethodLogger(h, m uint64) *TruncatingMethodLogger

	/* 5 unexporteds ... *//* 5 unexporteds: */
	 type bufferedSink (struct)

		Fields (total 7, none are exported)
			/* 7 unexporteds ... *//* 7 unexporteds: */
			buf *bufio.Writer
				// buf is kept for flush.

			closer io.Closer
			done chan struct{}
			flusherStarted bool
			mu sync.Mutex
			out Sink
				// out is built on buf.

			writeTicker *time.Ticker
		Methods (total 3, in which 2 are exported)
			(*bufferedSink) Close() error
			(*bufferedSink) Write(e *binlogpb.GrpcLogEntry) error
			/* one unexported ... *//* one unexported: */
			(*bufferedSink) startFlushGoroutine()
		Implements (at least 2, both are exported)
			*bufferedSink : Sink
			*bufferedSink : io.Closer

	 type callIDGenerator (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			id uint64
		Methods (total 2, neither is exported)
			/* 2 unexporteds ... *//* 2 unexporteds: */
			(*callIDGenerator) next() uint64
			(*callIDGenerator) reset()
				reset is for testing only, and doesn't need to be thread safe.

		As Types Of (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			  var idGen

	 type logger (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			config LoggerConfig
		Methods (total 6, in which 1 are exported)
			(*logger) GetMethodLogger(methodName string) MethodLogger
				getMethodLogger returns the MethodLogger for the given methodName.

				methodName should be in the format of "/service/method".

				Each MethodLogger returned by this method is a new instance. This is to
				generate sequence id within the call.

			/* 5 unexporteds ... *//* 5 unexporteds: */
			(*logger) fillMethodLoggerWithConfigString(config string) error
				fillMethodLoggerWithConfigString parses config, creates TruncatingMethodLogger and adds
				it to the right map in the logger.

			(*logger) setBlacklist(method string) error
				Set blacklist method for "-service/method".

			(*logger) setDefaultMethodLogger(ml *MethodLoggerConfig) error
				Set method logger for "*".

			(*logger) setMethodMethodLogger(method string, ml *MethodLoggerConfig) error
				Set method logger for "service/method".

				New MethodLogger with same method overrides the old one.

			(*logger) setServiceMethodLogger(service string, ml *MethodLoggerConfig) error
				Set method logger for "service/*".

				New MethodLogger with same service overrides the old one.

		Implements (at least one exported)
			*logger : Logger
		As Outputs Of (at least one unexported)
			/* at least one unexported ... *//* at least one unexported: */
			func newEmptyLogger() *logger

	 type noopSink (struct)

		Methods (total 2, both are exported)
			(*noopSink) Close() error
			(*noopSink) Write(*binlogpb.GrpcLogEntry) error
		Implements (at least 2, both are exported)
			*noopSink : Sink
			*noopSink : io.Closer

	 type writerSink (struct)

		Fields (only one, which is unexported)
			/* one unexported ... *//* one unexported: */
			out io.Writer
		Methods (total 2, both are exported)
			(*writerSink) Close() error
			(*writerSink) Write(e *binlogpb.GrpcLogEntry) error
		Implements (at least 2, both are exported)
			*writerSink : Sink
			*writerSink : io.Closer


Package-Level Functions (total 15, in which 7 are exported)

	 func GetLogger() Logger
		GetLogger gets the binary logger.

		Only call this at init time.

	 func GetMethodLogger(methodName string) MethodLogger
		GetMethodLogger returns the MethodLogger for the given methodName.

		methodName should be in the format of "/service/method".

		Each MethodLogger returned by this method is a new instance. This is to
		generate sequence id within the call.

	 func NewBufferedSink(o io.WriteCloser) Sink
		NewBufferedSink creates a binary log sink with the given WriteCloser.

		Write() marshals the proto message and writes it to the given writer. Each
		message is prefixed with a 4 byte big endian unsigned integer as the length.

		Content is kept in a buffer, and is flushed every 60 seconds.

		Close closes the WriteCloser.

	 func NewLoggerFromConfig(config LoggerConfig) Logger
		NewLoggerFromConfig builds a logger with the given LoggerConfig.

	 func NewLoggerFromConfigString(s string) Logger
		NewLoggerFromConfigString reads the string and build a logger. It can be used
		to build a new logger and assign it to binarylog.Logger.

		Example filter config strings:
		  - "" Nothing will be logged
		  - "*" All headers and messages will be fully logged.
		  - "*{h}" Only headers will be logged.
		  - "*{m:256}" Only the first 256 bytes of each message will be logged.
		  - "Foo/*" Logs every method in service Foo
		  - "Foo/*,-Foo/Bar" Logs every method in service Foo except method /Foo/Bar
		  - "Foo/*,Foo/Bar{m:256}" Logs the first 256 bytes of each message in method
		    /Foo/Bar, logs all headers and messages in every other method in service
		    Foo.

		If two configs exist for one certain method or service, the one specified
		later overrides the previous config.

	 func NewTruncatingMethodLogger(h, m uint64) *TruncatingMethodLogger
		NewTruncatingMethodLogger returns a new truncating method logger.

	 func SetLogger(l Logger)
		SetLogger sets the binary logger.

		Only call this at init time.

	/* 8 unexporteds ... *//* 8 unexporteds: */
	 func addrToProto(addr net.Addr) *binlogpb.Address
	 func init()
	 func mdToMetadataProto(md metadata.MD) *binlogpb.Metadata
	 func metadataKeyOmit(key string) bool
		metadataKeyOmit returns whether the metadata entry with this key should be
		omitted.

	 func newEmptyLogger() *logger
		newEmptyLogger creates an empty logger. The map fields need to be filled in
		using the set* functions.

	 func newWriterSink(w io.Writer) Sink
		newWriterSink creates a binary log sink with the given writer.

		Write() marshals the proto message and writes it to the given writer. Each
		message is prefixed with a 4 byte big endian unsigned integer as the length.

		No buffer is done, Close() doesn't try to close the writer.

	 func parseHeaderMessageLengthConfig(c string) (hdrLenStr, msgLenStr uint64, err error)
		Turn "{h:123;m:345}" into 123, 345.

		Return maxUInt if length is unspecified.

	 func parseMethodConfigAndSuffix(c string) (service, method, suffix string, _ error)
		Turn "service/method{h;m}" into "service", "method", "{h;m}".


Package-Level Variables (total 11, in which 4 are exported)

	  var AddrToProto func(addr net.Addr) *grpc_binarylog_v1.Address
		AddrToProto converts an address to a binary logging proto message. It's
		for testing only.

	  var AllLogger Logger
		AllLogger is a logger that logs all headers/messages for all RPCs. It's
		for testing only.

	  var DefaultSink Sink // TODO(blog): change this default (file in /tmp).
		DefaultSink is the sink where the logs will be written to. It's exported
		for the binarylog package to update.

	  var MdToMetadataProto func(md metadata.MD) *grpc_binarylog_v1.Metadata
		MdToMetadataProto converts metadata to a binary logging proto message.
		It's for testing only.

	/* 7 unexporteds ... *//* 7 unexporteds: */
	  var binLogger Logger
		binLogger is the global binary logger for the binary. One of this should be
		built at init time from the configuration (environment variable or flags).

		It is used to get a MethodLogger for each individual method.

	  var grpclogLogger grpclog.DepthLoggerV2
	  var headerConfigRegexp *regexp.Regexp
	  var headerMessageConfigRegexp *regexp.Regexp
	  var idGen callIDGenerator
	  var longMethodConfigRegexp *regexp.Regexp
	  var messageConfigRegexp *regexp.Regexp
Package-Level Constants (total 7, none are exported)

	/* 7 unexporteds ... *//* 7 unexporteds: */
	const bufFlushDuration time.Duration = 60000000000
	const headerConfigRegexpStr = "^{h(?::(\\d+))?}$"
	const headerMessageConfigRegexpStr = "^{h(?::(\\d+))?;m(?::(\\d+))?}$"
	const longMethodConfigRegexpStr = "^([\\w./]+)/((?:\\w+)|[*])(.+)?$"
		For "p.s/m" plus any suffix. Suffix will be parsed again. See test for
		expected output.

	const maxUInt uint64 = 18446744073709551615
		TODO: this const is only used by env_config now. But could be useful for
		other config. Move to binarylog.go if necessary.

	const messageConfigRegexpStr = "^{m(?::(\\d+))?}$"
	const optionalLengthRegexpStr = "(?::(\\d+))?" // Optional ":123".
		For suffix from above, "{h:123,m:123}". See test for expected output.

The pages are generated with Golds v0.4.9. (GOOS=linux GOARCH=amd64)