logbroker.proto 6.4 KB

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