Understanding the logging.edgelq.com service APIv1alpha2, in proto package ntt.logging.v1alpha2.

Service logging.edgelq.com in version v1alpha2, proto package ntt.logging.v1alpha2

Here is the list of resources supported in Logging service APIv1alpha2:

Log resource
LogDescriptor resource

Log Resource

Name patterns:

logs/{log}
projects/{project}/logs/{log}
organizations/{organization}/logs/{log}

Parent resources:

This section covers the methods and messages to interact with Log resource.

Log Methods

Here is the list of Log resource methods:

ListLogs method
CreateLogs method

ListLogs Method

ListLogs

rpc ListLogs(ListLogsRequest) returns (ListLogsResponse)

with the following messages:

ListLogsRequest request message
ListLogsResponse response message

Required Permissions:

services/logging.edgelq.com/permissions/logs.list

The equivalent REST API is:

GET /v1alpha2/logs

CreateLogs Method

CreateLogs

rpc CreateLogs(CreateLogsRequest) returns (CreateLogsResponse)

with the following messages:

CreateLogsRequest request message
CreateLogsResponse response message

Required Permissions:

services/logging.edgelq.com/permissions/logs.create

The equivalent REST API is:

POST /v1alpha2/logs (BODY: logs)

Log Messages

Here is the list of Log resource messages:

Log Message

Name	Type	Description
name	string (name of Log)	Name of Log. It contains scope + ID of the log. ID is a base64 encoded unique key that identifies tuple: scope service region_id version log_descriptor labels Key is not to be decoded outside of service, but treated as opaque string
scope	string	Contains scope from name field without resource ID. Used for internal purpose for filtering (logs are using custom store). Example formats are: - organization/umbrella - projects/mars_exploration - <system>
service	string	Service name, for example “devices.edgelq.com”
region	string	Region of the service to which log is assigned, for example “us-west2”
version	string	Associated service version, for example “v1alpha2”
log_descriptor	string (reference to LogDescriptor)	Associated log descriptor
labels	map<string, string>	List of query-able labels
time	.google.protobuf.Timestamp	Log timestamp
payload	.google.protobuf.Struct	Log payload

ListLogsRequest Message

Request message for method [ListLogs][ntt.logging.v1alpha2.ListLogs]

Name	Type	Description
parents	repeated string (parent name of Log)	Parent references of ntt.logging.v1alpha2.Log
filter	string (filter of Log)	Filter that specifies which logs should be returned
interval	TimeInterval	The time interval for which results should be returned. Only logs that contain data points in the specified interval are included in the response.
page_size	int32	Cap on a number of log entries to be included in a response. Number of logs in an actual response can be higher, since logs are read in bulk with second precision - exceed logs above the limit will share same timestamp as the logs below the limit. Results will be adjusted to the “end time” taken from interval field (adjusted also by page_token if provided).
page_token	string	Token which identifies next page with further results. Token should be taken from [ListLogsResponse.next_page_token][ntt.logging.v1alpha2.ListLogsResponse.next_page_token].

ListLogsResponse Message

Response message for method [ListLogs][ntt.logging.v1alpha2.ListLogs]

Name	Type	Description
logs	repeated Log	Logs that match the filter included in the request.
next_page_token	string	If there are more results than have been returned, then this field is set to a non-empty value. To see the additional results, use that value as `pageToken` in the next call to this method.
execution_errors	repeated Status	Query execution errors that may have caused the logs data returned to be incomplete.

ListLogsResponse.ErrorDetails Message

ErrorDetails is used when one of the queried regions fails to produce results. It is used in execution_errors field (see subfield ntt.rpc.Status.details).

Name	Type	Description
region_id	string	region id which failed to give results.

CreateLogsRequest Message

Request message for method [CreateLogs][ntt.logging.v1alpha2.CreateLogs]

Name	Type	Description
parent	string (parent name of Log)	Parent reference of ntt.logging.v1alpha2.Log
logs	repeated Log	List of logs to create/append. If they have specified name field, it must match provided parent field.

CreateLogsResponse Message

Response message for method [CreateLogs][ntt.logging.v1alpha2.CreateLogs]

Name	Type	Description
log_names	map<uint32s, string (name of Log)>	Log names indexed by Create position. All logs, except failed ones will be present. If all logs were written successfully, then map will have keys all from 0 to N-1.
failed_logs	repeated CreateLogsResponse.CreateError	Logs that failed to be created

CreateLogsResponse.CreateError Message

Describes the result of a failed request to write logs.

Name	Type	Description
logs	repeated Log	All logs that failed to be written. This field provides all of the context that would be needed to retry the operation.
status	Status	The status of the requested write operation.

LogDescriptor Resource

Name patterns:

logDescriptors/{log_descriptor}
projects/{project}/logDescriptors/{log_descriptor}
organizations/{organization}/logDescriptors/{log_descriptor}

Parent resources:

This section covers the methods and messages to interact with LogDescriptor resource.

LogDescriptor Methods

Here is the list of LogDescriptor resource methods:

GetLogDescriptor Method

GetLogDescriptor

rpc GetLogDescriptor(GetLogDescriptorRequest) returns (LogDescriptor)

with the following messages:

GetLogDescriptorRequest request message
LogDescriptor response message

Required Permissions:

services/logging.edgelq.com/permissions/logDescriptors.get

The equivalent REST API is:

GET /v1alpha2/{name=logDescriptors/*}

GET /v1alpha2/{name=projects/*/logDescriptors/*}

GET /v1alpha2/{name=organizations/*/logDescriptors/*}

BatchGetLogDescriptors Method

BatchGetLogDescriptors

rpc BatchGetLogDescriptors(BatchGetLogDescriptorsRequest) returns (BatchGetLogDescriptorsResponse)

with the following messages:

BatchGetLogDescriptorsRequest request message
BatchGetLogDescriptorsResponse response message

Required Permissions:

services/logging.edgelq.com/permissions/logDescriptors.batchGet

The equivalent REST API is:

GET /v1alpha2/logDescriptors:batchGet

ListLogDescriptors Method

ListLogDescriptors

rpc ListLogDescriptors(ListLogDescriptorsRequest) returns (ListLogDescriptorsResponse)

with the following messages:

ListLogDescriptorsRequest request message
ListLogDescriptorsResponse response message

Required Permissions:

services/logging.edgelq.com/permissions/logDescriptors.list

The equivalent REST API is:

GET /v1alpha2/logDescriptors

GET /v1alpha2/{parent=projects/*}/logDescriptors

GET /v1alpha2/{parent=organizations/*}/logDescriptors

WatchLogDescriptor Method

WatchLogDescriptor

rpc WatchLogDescriptor(WatchLogDescriptorRequest) returns (WatchLogDescriptorResponse)

with the following messages:

WatchLogDescriptorRequest request message
WatchLogDescriptorResponse response message

Required Permissions:

services/logging.edgelq.com/permissions/logDescriptors.watch

The equivalent REST API is:

POST /v1alpha2/{name=logDescriptors/*}:watch

POST /v1alpha2/{name=projects/*/logDescriptors/*}:watch

POST /v1alpha2/{name=organizations/*/logDescriptors/*}:watch

WatchLogDescriptors Method

WatchLogDescriptors

rpc WatchLogDescriptors(WatchLogDescriptorsRequest) returns (WatchLogDescriptorsResponse)

with the following messages:

WatchLogDescriptorsRequest request message
WatchLogDescriptorsResponse response message

Required Permissions:

services/logging.edgelq.com/permissions/logDescriptors.watch

The equivalent REST API is:

POST /v1alpha2/logDescriptors:watch

POST /v1alpha2/{parent=projects/*}/logDescriptors:watch

POST /v1alpha2/{parent=organizations/*}/logDescriptors:watch

CreateLogDescriptor Method

CreateLogDescriptor

rpc CreateLogDescriptor(CreateLogDescriptorRequest) returns (LogDescriptor)

with the following messages:

CreateLogDescriptorRequest request message
LogDescriptor response message

Required Permissions:

services/logging.edgelq.com/permissions/logDescriptors.create

The equivalent REST API is:

POST /v1alpha2/logDescriptors (BODY: log_descriptor)

POST /v1alpha2/{parent=projects/*}/logDescriptors

POST /v1alpha2/{parent=organizations/*}/logDescriptors

UpdateLogDescriptor Method

UpdateLogDescriptor

rpc UpdateLogDescriptor(UpdateLogDescriptorRequest) returns (LogDescriptor)

with the following messages:

UpdateLogDescriptorRequest request message
LogDescriptor response message

Required Permissions:

services/logging.edgelq.com/permissions/logDescriptors.update

The equivalent REST API is:

PUT /v1alpha2/{log_descriptor.name=logDescriptors/*} (BODY: log_descriptor)

PUT /v1alpha2/{log_descriptor.name=projects/*/logDescriptors/*}

PUT /v1alpha2/{log_descriptor.name=organizations/*/logDescriptors/*}

DeleteLogDescriptor Method

DeleteLogDescriptor

rpc DeleteLogDescriptor(DeleteLogDescriptorRequest) returns (Empty)

with the following messages:

DeleteLogDescriptorRequest request message
Empty response message

Required Permissions:

services/logging.edgelq.com/permissions/logDescriptors.delete

The equivalent REST API is:

DELETE /v1alpha2/{name=logDescriptors/*}

DELETE /v1alpha2/{name=projects/*/logDescriptors/*}

DELETE /v1alpha2/{name=organizations/*/logDescriptors/*}

LogDescriptor Messages

Here is the list of LogDescriptor resource messages:

LogDescriptor message
GetLogDescriptorRequest message
BatchGetLogDescriptorsRequest message
BatchGetLogDescriptorsResponse message
ListLogDescriptorsRequest message
ListLogDescriptorsResponse message
WatchLogDescriptorRequest message
WatchLogDescriptorResponse message
WatchLogDescriptorsRequest message
WatchLogDescriptorsResponse message
WatchLogDescriptorsResponse.PageTokenChange message
CreateLogDescriptorRequest message
CreateLogDescriptorRequest.ResponseMask message
UpdateLogDescriptorRequest message
UpdateLogDescriptorRequest.CAS message
UpdateLogDescriptorRequest.ResponseMask message
DeleteLogDescriptorRequest message

LogDescriptor Message

Name	Type	Description
name	string (name of LogDescriptor)	Name of LogDescriptor - contains service name followed by name defined by developer, separated by ‘/’ sign. Example name: “devices.edgelq.com/DeviceFailure”
display_name	string	Optional. A concise name for the log type that might be displayed in user interfaces. It should be a Title Cased Noun Phrase, without any article or other determiners.
description	string	Optional. A detailed description of the log type that might be used in documentation.
labels	repeated LabelDescriptor	A set of labels used to describe instances of this log type.
promoted_label_key_sets	repeated LabelKeySet	Promoted Label Key Sets allow defining multiple indexing rules for underlying backend enabling query optimizations.
metadata	Meta	Metadata

GetLogDescriptorRequest Message

A request message of the GetLogDescriptor method.

Name	Type	Description
name	string (name of LogDescriptor)	Name of ntt.logging.v1alpha2.LogDescriptor
field_mask	.google.protobuf.FieldMask	A list of extra fields to be obtained for each response item on top of fields defined by request field view
view	View	View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetLogDescriptorsRequest Message

A request message of the BatchGetLogDescriptors method.

Name	Type	Description
names	repeated string (name of LogDescriptor)	Names of LogDescriptors
field_mask	.google.protobuf.FieldMask	A list of extra fields to be obtained for each response item on top of fields defined by request field view
view	View	View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetLogDescriptorsResponse Message

A response message of the BatchGetLogDescriptors method.

Name	Type	Description
log_descriptors	repeated LogDescriptor	found LogDescriptors
missing	repeated string (name of LogDescriptor)	list of not found LogDescriptors

ListLogDescriptorsRequest Message

A request message of the ListLogDescriptors method.

Name	Type	Description
parent	string (parent name of LogDescriptor)	Parent name of ntt.logging.v1alpha2.LogDescriptor
page_size	int32	Requested page size. Server may return fewer LogDescriptors than requested. If unspecified, server will pick an appropriate default.
page_token	string (cursor of LogDescriptor)	A token identifying a page of results the server should return. Typically, this is the value of ListLogDescriptorsResponse.next_page_token.
order_by	string (orderBy of LogDescriptor)	Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter	string (filter of LogDescriptor)	Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask	.google.protobuf.FieldMask	A list of extra fields to be obtained for each response item on top of fields defined by request field view
view	View	View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info	bool	Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListLogDescriptorsResponse Message

A response message of the ListLogDescriptors method.

Name	Type	Description
log_descriptors	repeated LogDescriptor	The list of LogDescriptors
prev_page_token	string (cursor of LogDescriptor)	A token to retrieve previous page of results. Pass this value in the ListLogDescriptorsRequest.page_token.
next_page_token	string (cursor of LogDescriptor)	A token to retrieve next page of results. Pass this value in the ListLogDescriptorsRequest.page_token.
current_offset	int32	Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count	int32	Number of total LogDescriptors across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchLogDescriptorRequest Message

A request message of the WatchLogDescriptor method.

Name	Type	Description
name	string (name of LogDescriptor)	Name of ntt.logging.v1alpha2.LogDescriptor
field_mask	.google.protobuf.FieldMask	A list of extra fields to be obtained for each response item on top of fields defined by request field view
view	View	View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchLogDescriptorResponse Message

A response message of the WatchLogDescriptor method.

Name	Type	Description
change	LogDescriptorChange

WatchLogDescriptorsRequest Message

A request message of the WatchLogDescriptors method.

Name	Type	Description
type	WatchType	Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent	string (parent name of LogDescriptor)	Parent name of ntt.logging.v1alpha2.LogDescriptor
page_size	int32	Requested page size. Server may return fewer LogDescriptors than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token	string (cursor of LogDescriptor)	A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by	string (orderBy of LogDescriptor)	Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token	string	A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time	.google.protobuf.Timestamp	Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter	string (filter of LogDescriptor)	Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask	.google.protobuf.FieldMask	A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to LogDescriptor that don’t affect any of masked fields won’t be sent back.
view	View	View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to LogDescriptor that don’t affect any of masked fields won’t be sent back.
max_chunk_size	int32	Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchLogDescriptorsResponse Message

A response message of the WatchLogDescriptors method.

Name	Type	Description
log_descriptor_changes	repeated LogDescriptorChange	Changes of LogDescriptors
is_current	bool	If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All LogDescriptors will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change	WatchLogDescriptorsResponse.PageTokenChange	When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token	string	Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size	int64	Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset	bool	In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset	bool	In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (LogDescriptors will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchLogDescriptorsResponse.PageTokenChange Message

Name	Type	Description
prev_page_token	string (cursor of LogDescriptor)	New token to retrieve previous page of results.
next_page_token	string (cursor of LogDescriptor)	New token to retrieve next page of results.

CreateLogDescriptorRequest Message

A request message of the CreateLogDescriptor method.

Name	Type	Description
parent	string (parent name of LogDescriptor)	Parent name of ntt.logging.v1alpha2.LogDescriptor
log_descriptor	LogDescriptor	LogDescriptor resource body
response_mask	CreateLogDescriptorRequest.ResponseMask	Optional masking applied to response object to reduce message response size.

CreateLogDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name	Type	Description
skip_entire_response_body	bool	If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask	.google.protobuf.FieldMask	If this field is populated, then resource in response will contain only specific fields.

UpdateLogDescriptorRequest Message

A request message of the UpdateLogDescriptor method.

Name	Type	Description
log_descriptor	LogDescriptor	LogDescriptor resource body
update_mask	.google.protobuf.FieldMask	FieldMask applied to request - change will be applied only for fields in the mask
cas	UpdateLogDescriptorRequest.CAS	Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing	bool	If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask	UpdateLogDescriptorRequest.ResponseMask	reduce message response size.

UpdateLogDescriptorRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

Name	Type	Description
conditional_state	LogDescriptor	Conditional desired state of a resource before update.
field_mask	.google.protobuf.FieldMask	Field paths from conditional state of resource server should check and compare.

UpdateLogDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name	Type	Description
skip_entire_response_body	bool	If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only	bool	Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask	.google.protobuf.FieldMask	If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteLogDescriptorRequest Message

A request message of the DeleteLogDescriptor method.

Name	Type	Description
name	string (name of LogDescriptor)	Name of ntt.logging.v1alpha2.LogDescriptor
allow_missing	bool	If set to true, and the resource is not found, method will be successful and will not return NotFound error.

Logging Service Shared Methods and Messages

Logging Service Shared Messages

Here is the list of Logging service shared messages:

LabelDescriptor Message

Name	Type	Description
key	string	The label key.
description	string	Label description

LabelKeySet Message

LabelKeySet is used for defining PromotedLabelKeySets

Name	Type	Description
label_keys	repeated string

LogDescriptorChange Message

LogDescriptorChange is used by Watch notifications Responses to describe change of single LogDescriptor One of Added, Modified, Removed

Name	Type	Description
added	LogDescriptorChange.Added	Added is returned when watched document is added, either created or enters Query view
modified	LogDescriptorChange.Modified	Modified is returned when watched document is modified
current	LogDescriptorChange.Current	Current is returned in stateless watch when document enters query view or is modified within.
removed	LogDescriptorChange.Removed	Removed is returned when LogDescriptor is deleted or leaves Query view

LogDescriptorChange.Added Message

LogDescriptor has been added to query view

Name	Type	Description
log_descriptor	LogDescriptor
view_index	int32	Integer describing index of added LogDescriptor in resulting query view.

LogDescriptorChange.Current Message

LogDescriptor has been added or modified in a query view. Version used for stateless watching

Name	Type	Description
log_descriptor	LogDescriptor

LogDescriptorChange.Modified Message

LogDescriptor changed some of it’s fields - contains either full document or masked change

Name	Type	Description
name	string (name of LogDescriptor)	Name of modified LogDescriptor
log_descriptor	LogDescriptor	New version of LogDescriptor or masked difference, depending on mask_changes instrumentation of issued [WatchLogDescriptorRequest] or [WatchLogDescriptorsRequest]
field_mask	.google.protobuf.FieldMask	Used when mask_changes is set, contains field paths of modified properties.
previous_view_index	int32	Previous view index specifies previous position of modified LogDescriptor. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index	int32	Integer specifying LogDescriptor new index in resulting query view.

LogDescriptorChange.Removed Message

Removed is returned when LogDescriptor is deleted or leaves Query view

Name	Type	Description
name	string (name of LogDescriptor)
view_index	int32	Integer specifying removed LogDescriptor index. Not populated in stateless watch type.

TimeInterval Message

A time interval extending just after a start time through an end time. If the start time is the same as the end time, then the interval represents a single point in time.

Name	Type	Description
end_time	.google.protobuf.Timestamp	Optional - end of the time interval. If not provided, current time will be assumed.
start_time	.google.protobuf.Timestamp	Required. The beginning of the time interval. The start time must not be later than the end time.