go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/logdog/api/logpb/butler.proto (about)

     1  // Copyright 2015 The LUCI Authors. All rights reserved.
     2  // Use of this source code is governed under the Apache License, Version 2.0
     3  // that can be found in the LICENSE file.
     4  
     5  syntax = "proto3";
     6  
     7  package logpb;
     8  
     9  option go_package = "go.chromium.org/luci/logdog/api/logpb";
    10  
    11  import "go.chromium.org/luci/logdog/api/logpb/log.proto";
    12  import "google/protobuf/timestamp.proto";
    13  
    14  /*
    15   * ButlerMetadata appears as a frame at the beginning of Butler published data
    16   * to describe the remainder of the contents.
    17   */
    18  message ButlerMetadata {
    19    /*
    20     * This enumerates the possible contents of published Butler data.
    21     */
    22    enum ContentType {
    23      /* An invalid content type. Do not use. */
    24      Invalid = 0;
    25      /* The published data is a ButlerLogBundle protobuf message. */
    26      ButlerLogBundle = 1;
    27    }
    28    /* This is the type of data in the subsequent frame. */
    29    ContentType type = 1;
    30  
    31    /* Compression scheme of attached data. */
    32    enum Compression {
    33      NONE = 0;
    34      ZLIB = 1;
    35    }
    36    Compression compression = 2;
    37  
    38    /* The protobuf version string (see version.go). */
    39    string proto_version = 3;
    40  }
    41  
    42  /*
    43   * A message containing log data in transit from the Butler.
    44   *
    45   * The Butler is capable of conserving bandwidth by bundling collected log
    46   * messages together into this protocol buffer. Based on Butler bundling
    47   * settings, this message can represent anything from a single LogRecord to
    48   * multiple LogRecords belonging to several different streams.
    49   *
    50   * Entries in a Log Bundle are fully self-descriptive: no additional information
    51   * is needed to fully associate the contained data with its proper place in
    52   * the source log stream.
    53   */
    54  message ButlerLogBundle {
    55    /*
    56     * (DEPRECATED) Stream source information. Now supplied during prefix
    57     * registration.
    58     */
    59    string deprecated_source = 1;
    60  
    61    /* The timestamp when this bundle was generated.
    62     *
    63     * This field will be used for debugging and internal accounting.
    64     */
    65    google.protobuf.Timestamp timestamp = 2;
    66  
    67    /*
    68     * A bundle Entry describes a set of LogEntry messages originating from the
    69     * same log stream.
    70     */
    71    message Entry {
    72      /*
    73       * The descriptor for this entry's log stream.
    74       *
    75       * Each LogEntry in the "logs" field is shares this common descriptor.
    76       */
    77      logpb.LogStreamDescriptor desc = 1;
    78  
    79      /* (DEPRECATED) Per-entry secret replaced with Butler-wide secret. */
    80      bytes deprecated_entry_secret = 2;
    81  
    82      /*
    83       * Whether this log entry terminates its stream.
    84       *
    85       * If present and "true", this field declares that this Entry is the last
    86       * such entry in the stream. This fact is recorded by the Collector and
    87       * registered with the Coordinator. The largest stream prefix in this Entry
    88       * will be bound the stream's LogEntry records to [0:largest_prefix]. Once
    89       * all messages in that range have been received, the log may be archived.
    90       *
    91       * Further log entries belonging to this stream with stream indices
    92       * exceeding the terminal log's index will be discarded.
    93       */
    94      bool terminal = 3;
    95  
    96      /*
    97       * If terminal is true, this is the terminal stream index; that is, the last
    98       * message index in the stream.
    99       */
   100      uint64 terminal_index = 4;
   101  
   102      /*
   103       * Log entries attached to this record. These MUST be sequential.
   104       *
   105       * This is the main log entry content.
   106       */
   107      repeated logpb.LogEntry logs = 5;
   108    }
   109  
   110    /**
   111     * Each Entry is an individual set of log records for a given log stream.
   112     */
   113    repeated Entry entries = 3;
   114  
   115    /** Project specifies which luci-config project this stream belongs to. */
   116    string project = 4;
   117  
   118    /**
   119     * The log stream prefix that is shared by all bundled streams.
   120     *
   121     * This prefix is valid within the supplied project scope.
   122     */
   123    string prefix = 5;
   124  
   125    /*
   126     * The log prefix's secret value (required).
   127     *
   128     * The secret is bound to all log streams that share the supplied Prefix, and
   129     * The Coordinator will record the secret associated with a given log Prefix,
   130     * but will not expose the secret to users.
   131     *
   132     * The Collector will check the secret prior to ingesting logs. If the
   133     * secret doesn't match the value recorded by the Coordinator, the log
   134     * will be discarded.
   135     *
   136     * This ensures that only the Butler instance that generated the log stream
   137     * can emit log data for that stream. It also ensures that only authenticated
   138     * users can write to a Prefix.
   139     */
   140    bytes secret = 6;
   141  }