1 // Copyright 2018 Google LLC.
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
7 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 package google.logging.v2;
20 import "google/api/annotations.proto";
21 import "google/api/monitored_resource.proto";
22 import "google/logging/v2/log_entry.proto";
23 import "google/protobuf/duration.proto";
24 import "google/protobuf/empty.proto";
25 import "google/protobuf/timestamp.proto";
26 import "google/rpc/status.proto";
28 option cc_enable_arenas = true;
29 option csharp_namespace = "Google.Cloud.Logging.V2";
30 option go_package = "google.golang.org/genproto/googleapis/logging/v2;logging";
31 option java_multiple_files = true;
32 option java_outer_classname = "LoggingProto";
33 option java_package = "com.google.logging.v2";
34 option php_namespace = "Google\\Cloud\\Logging\\V2";
36 // Service for ingesting and querying logs.
37 service LoggingServiceV2 {
38 // Deletes all the log entries in a log.
39 // The log reappears if it receives new entries.
40 // Log entries written shortly before the delete operation might not be
42 rpc DeleteLog(DeleteLogRequest) returns (google.protobuf.Empty) {
43 option (google.api.http) = {
44 delete: "/v2/{log_name=projects/*/logs/*}"
45 additional_bindings { delete: "/v2/{log_name=organizations/*/logs/*}" }
46 additional_bindings { delete: "/v2/{log_name=folders/*/logs/*}" }
47 additional_bindings { delete: "/v2/{log_name=billingAccounts/*/logs/*}" }
51 // Writes log entries to Logging. This API method is the
52 // only way to send log entries to Logging. This method
53 // is used, directly or indirectly, by the Logging agent
54 // (fluentd) and all logging libraries configured to use Logging.
55 // A single request may contain log entries for a maximum of 1000
56 // different resources (projects, organizations, billing accounts or
58 rpc WriteLogEntries(WriteLogEntriesRequest)
59 returns (WriteLogEntriesResponse) {
60 option (google.api.http) = {
61 post: "/v2/entries:write"
66 // Lists log entries. Use this method to retrieve log entries from
67 // Logging. For ways to export log entries, see
68 // [Exporting Logs](/logging/docs/export).
69 rpc ListLogEntries(ListLogEntriesRequest) returns (ListLogEntriesResponse) {
70 option (google.api.http) = {
71 post: "/v2/entries:list"
76 // Lists the descriptors for monitored resource types used by Logging.
77 rpc ListMonitoredResourceDescriptors(ListMonitoredResourceDescriptorsRequest)
78 returns (ListMonitoredResourceDescriptorsResponse) {
79 option (google.api.http) = {
80 get: "/v2/monitoredResourceDescriptors"
84 // Lists the logs in projects, organizations, folders, or billing accounts.
85 // Only logs that have entries are listed.
86 rpc ListLogs(ListLogsRequest) returns (ListLogsResponse) {
87 option (google.api.http) = {
88 get: "/v2/{parent=*/*}/logs"
89 additional_bindings { get: "/v2/{parent=projects/*}/logs" }
90 additional_bindings { get: "/v2/{parent=organizations/*}/logs" }
91 additional_bindings { get: "/v2/{parent=folders/*}/logs" }
92 additional_bindings { get: "/v2/{parent=billingAccounts/*}/logs" }
97 // The parameters to DeleteLog.
98 message DeleteLogRequest {
99 // Required. The resource name of the log to delete:
101 // "projects/[PROJECT_ID]/logs/[LOG_ID]"
102 // "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
103 // "billingAccounts/[BILLING_ACCOUNT_ID]/logs/[LOG_ID]"
104 // "folders/[FOLDER_ID]/logs/[LOG_ID]"
106 // `[LOG_ID]` must be URL-encoded. For example,
107 // `"projects/my-project-id/logs/syslog"`,
108 // `"organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"`.
109 // For more information about log names, see
110 // [LogEntry][google.logging.v2.LogEntry].
114 // The parameters to WriteLogEntries.
115 message WriteLogEntriesRequest {
116 // Optional. A default log resource name that is assigned to all log entries
117 // in `entries` that do not specify a value for `log_name`:
119 // "projects/[PROJECT_ID]/logs/[LOG_ID]"
120 // "organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
121 // "billingAccounts/[BILLING_ACCOUNT_ID]/logs/[LOG_ID]"
122 // "folders/[FOLDER_ID]/logs/[LOG_ID]"
124 // `[LOG_ID]` must be URL-encoded. For example:
126 // "projects/my-project-id/logs/syslog"
127 // "organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity"
129 // The permission <code>logging.logEntries.create</code> is needed on each
130 // project, organization, billing account, or folder that is receiving
131 // new log entries, whether the resource is specified in
132 // <code>logName</code> or in an individual log entry.
135 // Optional. A default monitored resource object that is assigned to all log
136 // entries in `entries` that do not specify a value for `resource`. Example:
138 // { "type": "gce_instance",
140 // "zone": "us-central1-a", "instance_id": "00000000000000000000" }}
142 // See [LogEntry][google.logging.v2.LogEntry].
143 google.api.MonitoredResource resource = 2;
145 // Optional. Default labels that are added to the `labels` field of all log
146 // entries in `entries`. If a log entry already has a label with the same key
147 // as a label in this parameter, then the log entry's label is not changed.
148 // See [LogEntry][google.logging.v2.LogEntry].
149 map<string, string> labels = 3;
151 // Required. The log entries to send to Logging. The order of log
152 // entries in this list does not matter. Values supplied in this method's
153 // `log_name`, `resource`, and `labels` fields are copied into those log
154 // entries in this list that do not include values for their corresponding
155 // fields. For more information, see the
156 // [LogEntry][google.logging.v2.LogEntry] type.
158 // If the `timestamp` or `insert_id` fields are missing in log entries, then
159 // this method supplies the current time or a unique identifier, respectively.
160 // The supplied values are chosen so that, among the log entries that did not
161 // supply their own values, the entries earlier in the list will sort before
162 // the entries later in the list. See the `entries.list` method.
164 // Log entries with timestamps that are more than the
165 // [logs retention period](/logging/quota-policy) in the past or more than
166 // 24 hours in the future will not be available when calling `entries.list`.
167 // However, those log entries can still be exported with
168 // [LogSinks](/logging/docs/api/tasks/exporting-logs).
170 // To improve throughput and to avoid exceeding the
171 // [quota limit](/logging/quota-policy) for calls to `entries.write`,
172 // you should try to include several log entries in this list,
173 // rather than calling this method for each individual log entry.
174 repeated LogEntry entries = 4;
176 // Optional. Whether valid entries should be written even if some other
177 // entries fail due to INVALID_ARGUMENT or PERMISSION_DENIED errors. If any
178 // entry is not written, then the response status is the error associated
179 // with one of the failed entries and the response includes error details
180 // keyed by the entries' zero-based index in the `entries.write` method.
181 bool partial_success = 5;
183 // Optional. If true, the request should expect normal response, but the
184 // entries won't be persisted nor exported. Useful for checking whether the
185 // logging API endpoints are working properly before sending valuable data.
189 // Result returned from WriteLogEntries.
191 message WriteLogEntriesResponse {}
193 // Error details for WriteLogEntries with partial success.
194 message WriteLogEntriesPartialErrors {
195 // When `WriteLogEntriesRequest.partial_success` is true, records the error
196 // status for entries that were not written due to a permanent error, keyed
197 // by the entry's zero-based index in `WriteLogEntriesRequest.entries`.
199 // Failed requests for which no entries are written will not include
201 map<int32, google.rpc.Status> log_entry_errors = 1;
204 // The parameters to `ListLogEntries`.
205 message ListLogEntriesRequest {
206 // Deprecated. Use `resource_names` instead. One or more project identifiers
207 // or project numbers from which to retrieve log entries. Example:
208 // `"my-project-1A"`. If present, these project identifiers are converted to
209 // resource name format and added to the list of resources in
211 repeated string project_ids = 1 [deprecated = true];
213 // Required. Names of one or more parent resources from which to
214 // retrieve log entries:
216 // "projects/[PROJECT_ID]"
217 // "organizations/[ORGANIZATION_ID]"
218 // "billingAccounts/[BILLING_ACCOUNT_ID]"
219 // "folders/[FOLDER_ID]"
221 // Projects listed in the `project_ids` field are added to this list.
222 repeated string resource_names = 8;
224 // Optional. A filter that chooses which log entries to return. See [Advanced
225 // Logs Filters](/logging/docs/view/advanced_filters). Only log entries that
226 // match the filter are returned. An empty filter matches all log entries in
227 // the resources listed in `resource_names`. Referencing a parent resource
228 // that is not listed in `resource_names` will cause the filter to return no
230 // The maximum length of the filter is 20000 characters.
233 // Optional. How the results should be sorted. Presently, the only permitted
234 // values are `"timestamp asc"` (default) and `"timestamp desc"`. The first
235 // option returns entries in order of increasing values of
236 // `LogEntry.timestamp` (oldest first), and the second option returns entries
237 // in order of decreasing timestamps (newest first). Entries with equal
238 // timestamps are returned in order of their `insert_id` values.
241 // Optional. The maximum number of results to return from this request.
242 // Non-positive values are ignored. The presence of `next_page_token` in the
243 // response indicates that more results might be available.
246 // Optional. If present, then retrieve the next batch of results from the
247 // preceding call to this method. `page_token` must be the value of
248 // `next_page_token` from the previous response. The values of other method
249 // parameters should be identical to those in the previous call.
250 string page_token = 5;
253 // Result returned from `ListLogEntries`.
254 message ListLogEntriesResponse {
255 // A list of log entries. If `entries` is empty, `nextPageToken` may still be
256 // returned, indicating that more entries may exist. See `nextPageToken` for
258 repeated LogEntry entries = 1;
260 // If there might be more results than those appearing in this response, then
261 // `nextPageToken` is included. To get the next set of results, call this
262 // method again using the value of `nextPageToken` as `pageToken`.
264 // If a value for `next_page_token` appears and the `entries` field is empty,
265 // it means that the search found no log entries so far but it did not have
266 // time to search all the possible log entries. Retry the method with this
267 // value for `page_token` to continue the search. Alternatively, consider
268 // speeding up the search by changing your filter to specify a single log name
269 // or resource type, or to narrow the time range of the search.
270 string next_page_token = 2;
273 // The parameters to ListMonitoredResourceDescriptors
274 message ListMonitoredResourceDescriptorsRequest {
275 // Optional. The maximum number of results to return from this request.
276 // Non-positive values are ignored. The presence of `nextPageToken` in the
277 // response indicates that more results might be available.
280 // Optional. If present, then retrieve the next batch of results from the
281 // preceding call to this method. `pageToken` must be the value of
282 // `nextPageToken` from the previous response. The values of other method
283 // parameters should be identical to those in the previous call.
284 string page_token = 2;
287 // Result returned from ListMonitoredResourceDescriptors.
288 message ListMonitoredResourceDescriptorsResponse {
289 // A list of resource descriptors.
290 repeated google.api.MonitoredResourceDescriptor resource_descriptors = 1;
292 // If there might be more results than those appearing in this response, then
293 // `nextPageToken` is included. To get the next set of results, call this
294 // method again using the value of `nextPageToken` as `pageToken`.
295 string next_page_token = 2;
298 // The parameters to ListLogs.
299 message ListLogsRequest {
300 // Required. The resource name that owns the logs:
302 // "projects/[PROJECT_ID]"
303 // "organizations/[ORGANIZATION_ID]"
304 // "billingAccounts/[BILLING_ACCOUNT_ID]"
305 // "folders/[FOLDER_ID]"
308 // Optional. The maximum number of results to return from this request.
309 // Non-positive values are ignored. The presence of `nextPageToken` in the
310 // response indicates that more results might be available.
313 // Optional. If present, then retrieve the next batch of results from the
314 // preceding call to this method. `pageToken` must be the value of
315 // `nextPageToken` from the previous response. The values of other method
316 // parameters should be identical to those in the previous call.
317 string page_token = 3;
320 // Result returned from ListLogs.
321 message ListLogsResponse {
322 // A list of log names. For example,
323 // `"projects/my-project/syslog"` or
324 // `"organizations/123/cloudresourcemanager.googleapis.com%2Factivity"`.
325 repeated string log_names = 3;
327 // If there might be more results than those appearing in this response, then
328 // `nextPageToken` is included. To get the next set of results, call this
329 // method again using the value of `nextPageToken` as `pageToken`.
330 string next_page_token = 2;