vendor/github.com/docker/swarmkit/api/logbroker.proto

   1 syntax = "proto3";
   2
   3 package docker.swarmkit.v1;
   4
   5 import "gogoproto/gogo.proto";
   6 import "google/protobuf/timestamp.proto";
   7 import "plugin/plugin.proto";
   8
   9 // LogStream defines the stream from which the log message came.
  10 enum LogStream {
  11         option (gogoproto.goproto_enum_prefix) = false;
  12         option (gogoproto.enum_customname) = "LogStream";
  13
  14         LOG_STREAM_UNKNOWN = 0 [(gogoproto.enumvalue_customname) = "LogStreamUnknown"];
  15         LOG_STREAM_STDOUT = 1 [(gogoproto.enumvalue_customname) = "LogStreamStdout"];
  16         LOG_STREAM_STDERR = 2 [(gogoproto.enumvalue_customname) = "LogStreamStderr"];
  17 }
  18
  19 message LogSubscriptionOptions {
  20         // Streams defines which log streams should be sent from the task source.
  21         // Empty means send all the messages.
  22         repeated LogStream streams = 1 [packed=false];
  23
  24         // Follow instructs the publisher to continue sending log messages as they
  25         // are produced, after satisfying the initial query.
  26         bool follow = 2;
  27
  28         // Tail defines how many messages relative to the log stream to send when
  29         // starting the stream.
  30         //
  31         // Positive values will skip that number of messages from the start of the
  32         // stream before publishing.
  33         //
  34         // Negative values will specify messages relative to the end of the stream,
  35         // offset by one. We can say that the last (-n-1) lines are returned when n
  36         // < 0. As reference, -1 would mean send no log lines (typically used with
  37         // follow), -2 would return the last log line, -11 would return the last 10
  38         // and so on.
  39         //
  40         // The default value of zero will return all logs.
  41         //
  42         // Note that this is very different from the Docker API.
  43         int64 tail = 3;
  44
  45         // Since indicates that only log messages produced after this timestamp
  46         // should be sent.
  47         // Note: can't use stdtime because this field is nullable.
  48         google.protobuf.Timestamp since = 4;
  49 }
  50
  51 // LogSelector will match logs from ANY of the defined parameters.
  52 //
  53 // For the best effect, the client should use the least specific parameter
  54 // possible. For example, if they want to listen to all the tasks of a service,
  55 // they should use the service id, rather than specifying the individual tasks.
  56 message LogSelector {
  57         repeated string service_ids = 1;
  58         repeated string node_ids = 2;
  59         repeated string task_ids = 3;
  60 }
  61
  62 // LogContext marks the context from which a log message was generated.
  63 message LogContext {
  64         string service_id = 1;
  65         string node_id = 2;
  66         string task_id = 3;
  67 }
  68
  69 // LogAttr is an extra key/value pair that may be have been set by users
  70 message LogAttr {
  71         string key = 1;
  72         string value = 2;
  73 }
  74
  75 // LogMessage
  76 message LogMessage {
  77         // Context identifies the source of the log message.
  78         LogContext context = 1 [(gogoproto.nullable) = false];
  79
  80         // Timestamp is the time at which the message was generated.
  81         // Note: can't use stdtime because this field is nullable.
  82         google.protobuf.Timestamp timestamp = 2;
  83
  84         // Stream identifies the stream of the log message, stdout or stderr.
  85         LogStream stream = 3;
  86
  87         // Data is the raw log message, as generated by the application.
  88         bytes data = 4;
  89
  90         // Attrs is a list of key value pairs representing additional log details
  91         // that may have been returned from the logger
  92         repeated LogAttr attrs = 5 [(gogoproto.nullable) = false];
  93 }
  94
  95 // Logs defines the methods for retrieving task logs messages from a cluster.
  96 service Logs {
  97         // SubscribeLogs starts a subscription with the specified selector and options.
  98         //
  99         // The subscription will be distributed to relevant nodes and messages will
 100         // be collected and sent via the returned stream.
 101         //
 102         // The subscription will end with an EOF.
 103         rpc SubscribeLogs(SubscribeLogsRequest) returns (stream SubscribeLogsMessage) {
 104                 option (docker.protobuf.plugin.tls_authorization) = { roles: "swarm-manager" };
 105         }
 106 }
 107
 108 message SubscribeLogsRequest {
 109         // LogSelector describes the logs to which the subscriber is
 110         LogSelector selector = 1;
 111
 112         LogSubscriptionOptions options = 2;
 113 }
 114
 115 message SubscribeLogsMessage {
 116         repeated LogMessage messages = 1 [(gogoproto.nullable) = false];
 117 }
 118
 119 // LogBroker defines the API used by the worker to send task logs back to a
 120 // manager. A client listens for subscriptions then optimistically retrieves
 121 // logs satisfying said subscriptions, calling PublishLogs for results that are
 122 // relevant.
 123 //
 124 // The structure of ListenSubscriptions is similar to the Dispatcher API but
 125 // decoupled to allow log distribution to work outside of the regular task
 126 // flow.
 127 service LogBroker {
 128         // ListenSubscriptions starts a subscription stream for the node. For each
 129         // message received, the node should attempt to satisfy the subscription.
 130         //
 131         // Log messages that match the provided subscription should be sent via
 132         // PublishLogs.
 133         rpc ListenSubscriptions(ListenSubscriptionsRequest) returns (stream SubscriptionMessage) {
 134                 option (docker.protobuf.plugin.tls_authorization) = {
 135                         roles: "swarm-worker"
 136                         roles: "swarm-manager"
 137                 };
 138         }
 139
 140         // PublishLogs receives sets of log messages destined for a single
 141         // subscription identifier.
 142         rpc PublishLogs(stream PublishLogsMessage) returns (PublishLogsResponse) {
 143                 option (docker.protobuf.plugin.tls_authorization) = {
 144                         roles: "swarm-worker"
 145                         roles: "swarm-manager"
 146                 };
 147         }
 148 }
 149
 150 // ListenSubscriptionsRequest is a placeholder to begin listening for
 151 // subscriptions.
 152 message ListenSubscriptionsRequest { }
 153
 154 // SubscriptionMessage instructs the listener to start publishing messages for
 155 // the stream or end a subscription.
 156 //
 157 // If Options.Follow == false, the worker should end the subscription on its own.
 158 message SubscriptionMessage {
 159         // ID identifies the subscription.
 160         string id = 1;
 161
 162         // Selector defines which sources should be sent for the subscription.
 163         LogSelector selector = 2;
 164
 165         // Options specify how the subscription should be satisfied.
 166         LogSubscriptionOptions options = 3;
 167
 168         // Close will be true if the node should shutdown the subscription with the
 169         // provided identifier.
 170         bool close = 4;
 171 }
 172
 173 message PublishLogsMessage {
 174         // SubscriptionID identifies which subscription the set of messages should
 175         // be sent to. We can think of this as a "mail box" for the subscription.
 176         string subscription_id = 1;
 177
 178         // Messages is the log message for publishing.
 179         repeated LogMessage messages = 2 [(gogoproto.nullable) = false];
 180
 181         // Close is a boolean for whether or not the client has completed its log
 182         // stream. When close is called, the manager can hang up the subscription.
 183         // Any further logs from this subscription are an error condition. Any
 184         // messages included when close is set can be discarded
 185         bool close = 3;
 186 }
 187
 188 message PublishLogsResponse { }