MCP Tools Reference: logging.googleapis.com

Tool: list_log_entries

Use this as the primary tool to search and retrieve log entries from Google Cloud Logging. It's essential for debugging application behavior, finding specific error messages, or auditing events. The 'filter' is powerful and can be used to select logs by severity, resource type, text content, and more. IMPORTANT: This tool will only work with a single resource project at a time. Calls with multiple resource projects will fail.

The following sample demonstrate how to use curl to invoke the list_log_entries MCP tool.

Curl Request 
                  
curl --location 'https://logging.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_log_entries",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

The parameters to ListLogEntries.

ListLogEntriesRequest

JSON representation 
{
  "projectIds": [
    string
  ],
  "resourceNames": [
    string
  ],
  "filter": string,
  "orderBy": string,
  "pageSize": integer,
  "pageToken": string
}
Fields
projectIds[]
(deprecated)

string

Optional. Deprecated. Use resource_names instead. One or more project identifiers or project numbers from which to retrieve log entries. Example: "my-project-1A".
resourceNames[]

string

Required. Names of one or more parent resources from which to retrieve log entries. Resources may either be resource containers or specific LogViews. For the case of resource containers, all logs ingested into that container will be returned regardless of which LogBuckets they are actually stored in - i.e. these queries may fan out to multiple regions. In the event of region unavailability, specify a specific set of LogViews that do not include the unavailable region.

  • projects/[PROJECT_ID]
  • organizations/[ORGANIZATION_ID]
  • billingAccounts/[BILLING_ACCOUNT_ID]
  • folders/[FOLDER_ID]

  • projects/[PROJECT_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]/views/[VIEW_ID]

  • organizations/[ORGANIZATION_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]/views/[VIEW_ID]
  • billingAccounts/[BILLING_ACCOUNT_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]/views/[VIEW_ID]
  • folders/[FOLDER_ID]/locations/[LOCATION_ID]/buckets/[BUCKET_ID]/views/[VIEW_ID]

Projects listed in the project_ids field are added to this list. A maximum of 100 resources may be specified in a single request.
filter

string

Optional. A filter that chooses which log entries to return. For more information, see Logging query language.

Only log entries that match the filter are returned. An empty filter matches all log entries in the resources listed in resource_names. Referencing a parent resource that is not listed in resource_names will cause the filter to return no results. The maximum length of a filter is 20,000 characters.

To make queries faster, you can make the filter more selective by using restrictions on indexed fields as well as limit the time range of the query by adding range restrictions on the timestamp field.
orderBy

string

Optional. How the results should be sorted. Presently, the only permitted values are "timestamp asc" (default) and "timestamp desc". The first option returns entries in order of increasing values of LogEntry.timestamp (oldest first), and the second option returns entries in order of decreasing timestamps (newest first). Entries with equal timestamps are returned in order of their insert_id values.

We recommend setting the order_by field to "timestamp desc" when listing recently ingested log entries. If not set, the default value of "timestamp asc" may take a long time to fetch matching logs that are only recently ingested.
pageSize

integer

Optional. The maximum number of results to return from this request. Default is 50. If the value is negative, the request is rejected.

The presence of next_page_token in the response indicates that more results might be available.
pageToken

string

Optional. If present, then retrieve the next batch of results from the preceding call to this method. page_token must be the value of next_page_token from the previous response. The values of other method parameters should be identical to those in the previous call.

Output Schema

Result returned from ListLogEntries.

ListLogEntriesResponse

JSON representation 
{
  "entries": [
    {
      object (LogEntry)
    }
  ],
  "nextPageToken": string
}
Fields
entries[]

object (LogEntry)

A list of log entries. If entries is empty, nextPageToken may still be returned, indicating that more entries may exist. See nextPageToken for more information.
nextPageToken

string

If there might be more results than those appearing in this response, then nextPageToken is included. To get the next set of results, call this method again using the value of nextPageToken as pageToken.

If a value for next_page_token appears and the entries field is empty, it means that the search found no log entries so far but it did not have time to search all the possible log entries. Retry the method with this value for page_token to continue the search. Alternatively, consider speeding up the search by changing your filter to specify a single log name or resource type, or to narrow the time range of the search.

LogEntry

JSON representation 
{
  "logName": string,
  "resource": {
    object (MonitoredResource)
  },
  "timestamp": string,
  "receiveTimestamp": string,
  "severity": enum (LogSeverity),
  "insertId": string,
  "httpRequest": {
    object (HttpRequest)
  },
  "labels": {
    string: string,
    ...
  },
  "metadata": {
    object (MonitoredResourceMetadata)
  },
  "operation": {
    object (LogEntryOperation)
  },
  "trace": string,
  "spanId": string,
  "traceSampled": boolean,
  "sourceLocation": {
    object (LogEntrySourceLocation)
  },
  "split": {
    object (LogSplit)
  },
  "errorGroups": [
    {
      object (LogErrorGroup)
    }
  ],
  "apphub": {
    object (AppHub)
  },
  "apphubDestination": {
    object (AppHub)
  },
  "apphubSource": {
    object (AppHub)
  },

  // Union field payload can be only one of the following:
  "protoPayload": {
    "@type": string,
    field1: ...,
    ...
  },
  "textPayload": string,
  "jsonPayload": {
    object
  }
  // End of list of possible types for union field payload.
}
Fields
logName

string

Required. The resource name of the log to which this log entry belongs:

"projects/[PROJECT_ID]/logs/[LOG_ID]"
"organizations/[ORGANIZATION_ID]/logs/[LOG_ID]"
"billingAccounts/[BILLING_ACCOUNT_ID]/logs/[LOG_ID]"
"folders/[FOLDER_ID]/logs/[LOG_ID]"

A project number may be used in place of PROJECT_ID. The project number is translated to its corresponding PROJECT_ID internally and the log_name field will contain PROJECT_ID in queries and exports.

[LOG_ID] must be URL-encoded within log_name. Example: "organizations/1234567890/logs/cloudresourcemanager.googleapis.com%2Factivity".

[LOG_ID] must be less than 512 characters long and can only include the following characters: upper and lower case alphanumeric characters, forward-slash, underscore, hyphen, and period.

For backward compatibility, if log_name begins with a forward-slash, such as /projects/..., then the log entry is processed as usual, but the forward-slash is removed. Listing the log entry will not show the leading slash and filtering for a log name with a leading slash will never return any results.
resource

object (MonitoredResource)

Required. The monitored resource that produced this log entry.

Example: a log entry that reports a database error would be associated with the monitored resource designating the particular database that reported the error.
timestamp

string (Timestamp format)

Optional. The time the event described by the log entry occurred. This time is used to compute the log entry's age and to enforce the logs retention period. If this field is omitted in a new log entry, then Logging assigns it the current time. Timestamps have nanosecond accuracy, but trailing zeros in the fractional seconds might be omitted when the timestamp is displayed.

Incoming log entries must have timestamps that don't exceed the logs retention period in the past, and that don't exceed 24 hours in the future. Log entries outside those time boundaries are rejected by Logging.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
receiveTimestamp

string (Timestamp format)

Output only. The time the log entry was received by Logging.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
severity

enum (LogSeverity)

Optional. The severity of the log entry. The default value is LogSeverity.DEFAULT.
insertId

string

Optional. A unique identifier for the log entry. If you provide a value, then Logging considers other log entries in the same project, with the same timestamp, and with the same insert_id to be duplicates which are removed in a single query result. However, there are no guarantees of de-duplication in the export of logs.

If the insert_id is omitted when writing a log entry, the Logging API assigns its own unique identifier in this field.

In queries, the insert_id is also used to order log entries that have the same log_name and timestamp values.
httpRequest

object (HttpRequest)

Optional. Information about the HTTP request associated with this log entry, if applicable.
labels

map (key: string, value: string)

Optional. A map of key, value pairs that provides additional information about the log entry. The labels can be user-defined or system-defined.

User-defined labels are arbitrary key, value pairs that you can use to classify logs.

System-defined labels are defined by cloud services for platform logs. They have two components - a service namespace component and the attribute name. For example: compute.googleapis.com/resource_name.

Cloud Logging truncates label keys that exceed 512 B and label values that exceed 64 KB upon their associated log entry being written. The truncation is indicated by an ellipsis at the end of the character string.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
metadata
(deprecated)

object (MonitoredResourceMetadata)

Output only. Deprecated. This field is not used by Logging. Any value written to it is cleared.
operation

object (LogEntryOperation)

Optional. Information about an operation associated with the log entry, if applicable.
trace

string

Optional. The trace ID being written to Cloud Trace in association with this log entry. For example, if your trace data is stored in the Cloud project "my-trace-project" and if the service that is creating the log entry receives a trace header that includes the trace ID "12345", then the service should use "12345".

The REST resource name of the trace is also supported, but using this format is not recommended. An example trace REST resource name is similar to "projects/my-trace-project/traces/12345".

The trace field provides the link between logs and traces. By using this field, you can navigate from a log entry to a trace.
spanId

string

Optional. The ID of the Cloud Trace span associated with the current operation in which the log is being written.

A Span represents a single operation within a trace. Whereas a trace may involve multiple different microservices running on multiple different machines, a span generally corresponds to a single logical operation being performed in a single instance of a microservice on one specific machine. Spans are the nodes within the tree that is a trace.

Applications that are instrumented for tracing will generally assign a new, unique span ID on each incoming request. It is also common to create and record additional spans corresponding to internal processing elements as well as issuing requests to dependencies.

The span ID is expected to be a 16-character, hexadecimal encoding of an 8-byte array and should not be zero. It should be unique within the trace and should, ideally, be generated in a manner that is uniformly random.

Example values:

  • 000000000000004a
  • 7a2190356c3fc94b
  • 0000f00300090021
  • d39223e101960076
traceSampled

boolean

Optional. The sampling decision of the span associated with the log entry at the time the log entry was created. This field corresponds to the sampled flag in the W3C trace-context specification. A non-sampled trace value is still useful as a request correlation identifier. The default is False.
sourceLocation

object (LogEntrySourceLocation)

Optional. Source code location information associated with the log entry, if any.
split

object (LogSplit)

Optional. Information indicating this LogEntry is part of a sequence of multiple log entries split from a single LogEntry.
errorGroups[]

object (LogErrorGroup)

Output only. The Error Reporting error groups associated with this LogEntry. Error Reporting sets the values for this field during error group creation.

For more information, see [View error details]( https://cloud.google.com/error-reporting/docs/viewing-errors#view_error_details)

This field isn't available during log routing
apphub

object (AppHub)

Output only. AppHub application metadata associated with this LogEntry. May be empty if there is no associated AppHub application or multiple associated applications (such as for VPC flow logs)
apphubDestination

object (AppHub)

Output only. AppHub application metadata associated with the destination application. This is only populated if the log represented "edge"-like data (such as for VPC flow logs) with a destination.
apphubSource

object (AppHub)

Output only. AppHub application metadata associated with the source application. This is only populated if the log represented "edge"-like data (such as for VPC flow logs) with a source.
Union field payload. The log entry payload, which can be one of multiple types. payload can be only one of the following:
protoPayload

object

The log entry payload, represented as a protocol buffer. Some Google Cloud Platform services use this field for their log entry payloads.

The following protocol buffer types are supported; user-defined types are not supported:

"type.googleapis.com/google.cloud.audit.AuditLog" "type.googleapis.com/google.appengine.logging.v1.RequestLog"

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.
textPayload

string

The log entry payload, represented as a Unicode string (UTF-8).
jsonPayload

object (Struct format)

The log entry payload, represented as a structure that is expressed as a JSON object.

MonitoredResource

JSON representation 
{
  "type": string,
  "labels": {
    string: string,
    ...
  }
}
Fields
type

string

Required. The monitored resource type. This field must match the type field of a MonitoredResourceDescriptor object. For example, the type of a Compute Engine VM instance is gce_instance. Some descriptors include the service name in the type; for example, the type of a Datastream stream is datastream.googleapis.com/Stream.
labels

map (key: string, value: string)

Required. Values for all of the labels listed in the associated monitored resource descriptor. For example, Compute Engine VM instances use the labels "project_id", "instance_id", and "zone".

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

LabelsEntry

JSON representation 
{
  "key": string,
  "value": string
}
Fields
key

string
value

string

Any

JSON representation 
{
  "typeUrl": string,
  "value": string
}
Fields
typeUrl

string

A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted).

In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:

  • If no scheme is provided, https is assumed.
  • An HTTP GET on the URL must yield a google.protobuf.Type value in binary format, or produce an error.
  • Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)

Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one.

Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.
value

string (bytes format)

Must be a valid serialized protocol buffer of the above specified type.

A base64-encoded string.

Struct

JSON representation 
{
  "fields": {
    string: value,
    ...
  }
}
Fields
fields

map (key: string, value: value (Value format))

Unordered map of dynamically typed values.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

JSON representation 
{
  "key": string,
  "value": value
}
Fields
key

string
value

value (Value format)

Value

JSON representation 
{

  // Union field kind can be only one of the following:
  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
  // End of list of possible types for union field kind.
}
Fields
Union field kind. The kind of value. kind can be only one of the following:
nullValue

null

Represents a null value.
numberValue

number

Represents a double value.
stringValue

string

Represents a string value.
boolValue

boolean

Represents a boolean value.
structValue

object (Struct format)

Represents a structured value.
listValue

array (ListValue format)

Represents a repeated Value.

ListValue

JSON representation 
{
  "values": [
    value
  ]
}
Fields
values[]

value (Value format)

Repeated field of dynamically typed values.

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

HttpRequest

JSON representation 
{
  "requestMethod": string,
  "requestUrl": string,
  "requestSize": string,
  "status": integer,
  "responseSize": string,
  "userAgent": string,
  "remoteIp": string,
  "serverIp": string,
  "referer": string,
  "latency": string,
  "cacheLookup": boolean,
  "cacheHit": boolean,
  "cacheValidatedWithOriginServer": boolean,
  "cacheFillBytes": string,
  "protocol": string
}
Fields
requestMethod

string

The request method. Examples: "GET", "HEAD", "PUT", "POST".
requestUrl

string

The scheme (http, https), the host name, the path and the query portion of the URL that was requested. Example: "http://example.com/some/info?color=red".
requestSize

string (int64 format)

The size of the HTTP request message in bytes, including the request headers and the request body.
status

integer

The response code indicating the status of response. Examples: 200, 404.
responseSize

string (int64 format)

The size of the HTTP response message sent back to the client, in bytes, including the response headers and the response body.
userAgent

string

The user agent sent by the client. Example: "Mozilla/4.0 (compatible; MSIE 6.0; Windows 98; Q312461; .NET CLR 1.0.3705)".
remoteIp

string

The IP address (IPv4 or IPv6) of the client that issued the HTTP request. This field can include port information. Examples: "192.168.1.1", "10.0.0.1:80", "FE80::0202:B3FF:FE1E:8329".
serverIp

string

The IP address (IPv4 or IPv6) of the origin server that the request was sent to. This field can include port information. Examples: "192.168.1.1", "10.0.0.1:80", "FE80::0202:B3FF:FE1E:8329".
referer

string

The referer URL of the request, as defined in HTTP/1.1 Header Field Definitions.
latency

string (Duration format)

The request processing latency on the server, from the time the request was received until the response was sent. For WebSocket connections, this field refers to the entire time duration of the connection.

A duration in seconds with up to nine fractional digits, ending with 's'. Example: "3.5s".
cacheLookup

boolean

Whether or not a cache lookup was attempted.
cacheHit

boolean

Whether or not an entity was served from cache (with or without validation).
cacheValidatedWithOriginServer

boolean

Whether or not the response was validated with the origin server before being served from cache. This field is only meaningful if cache_hit is True.
cacheFillBytes

string (int64 format)

The number of HTTP response bytes inserted into cache. Set only when a cache fill was attempted.
protocol

string

Protocol used for the request. Examples: "HTTP/1.1", "HTTP/2"

Duration

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years
nanos

integer

Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 seconds field and a positive or negative nanos field. For durations of one second or more, a non-zero value for the nanos field must be of the same sign as the seconds field. Must be from -999,999,999 to +999,999,999 inclusive.

LabelsEntry

JSON representation 
{
  "key": string,
  "value": string
}
Fields
key

string
value

string

MonitoredResourceMetadata

JSON representation 
{
  "systemLabels": {
    object
  },
  "userLabels": {
    string: string,
    ...
  }
}
Fields
systemLabels

object (Struct format)

Output only. Values for predefined system metadata labels. System labels are a kind of metadata extracted by Google, including "machine_image", "vpc", "subnet_id", "security_group", "name", etc. System label values can be only strings, Boolean values, or a list of strings. For example:

{ "name": "my-test-instance",
  "security_group": ["a", "b", "c"],
  "spot_instance": false }
userLabels

map (key: string, value: string)

Output only. A map of user-defined metadata labels.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

UserLabelsEntry

JSON representation 
{
  "key": string,
  "value": string
}
Fields
key

string
value

string

LogEntryOperation

JSON representation 
{
  "id": string,
  "producer": string,
  "first": boolean,
  "last": boolean
}
Fields
id

string

Optional. An arbitrary operation identifier. Log entries with the same identifier are assumed to be part of the same operation.
producer

string

Optional. An arbitrary producer identifier. The combination of id and producer must be globally unique. Examples for producer: "MyDivision.MyBigCompany.com", "github.com/MyProject/MyApplication".
first

boolean

Optional. Set this to True if this is the first log entry in the operation.
last

boolean

Optional. Set this to True if this is the last log entry in the operation.

LogEntrySourceLocation

JSON representation 
{
  "file": string,
  "line": string,
  "function": string
}
Fields
file

string

Optional. Source file name. Depending on the runtime environment, this might be a simple name or a fully-qualified name.
line

string (int64 format)

Optional. Line within the source file. 1-based; 0 indicates no line number available.
function

string

Optional. Human-readable name of the function or method being invoked, with optional context such as the class or package name. This information may be used in contexts such as the logs viewer, where a file and line number are less meaningful. The format can vary by language. For example: qual.if.ied.Class.method (Java), dir/package.func (Go), function (Python).

LogSplit

JSON representation 
{
  "uid": string,
  "index": integer,
  "totalSplits": integer
}
Fields
uid

string

A globally unique identifier for all log entries in a sequence of split log entries. All log entries with the same |LogSplit.uid| are assumed to be part of the same sequence of split log entries.
index

integer

The index of this LogEntry in the sequence of split log entries. Log entries are given |index| values 0, 1, ..., n-1 for a sequence of n log entries.
totalSplits

integer

The total number of log entries that the original LogEntry was split into.

LogErrorGroup

JSON representation 
{
  "id": string
}
Fields
id

string

The id is a unique identifier for a particular error group; it is the last part of the error group resource name: /project/[PROJECT_ID]/errors/[ERROR_GROUP_ID]. Example: COShysOX0r_51QE. The id is derived from key parts of the error-log content and is treated as Service Data. For information about how Service Data is handled, see Google Cloud Privacy Notice.

AppHub

JSON representation 
{
  "application": {
    object (AppHubApplication)
  },

  // Union field AppHubResource can be only one of the following:
  "service": {
    object (AppHubService)
  },
  "workload": {
    object (AppHubWorkload)
  }
  // End of list of possible types for union field AppHubResource.
}
Fields
application

object (AppHubApplication)

Metadata associated with the application.
Union field AppHubResource. AppHub service or workload. AppHubResource can be only one of the following:
service

object (AppHubService)

Metadata associated with the service.
workload

object (AppHubWorkload)

Metadata associated with the workload.

AppHubApplication

JSON representation 
{
  "container": string,
  "location": string,
  "id": string
}
Fields
container

string

Resource container that owns the application. Example: "projects/management_project"
location

string

Location associated with the Application. Example: "us-east1"
id

string

Application Id. Example: "my-app"

AppHubService

JSON representation 
{
  "id": string,
  "environmentType": string,
  "criticalityType": string
}
Fields
id

string

Service Id. Example: "my-service"
environmentType

string

Service environment type Example: "DEV"
criticalityType

string

Service criticality type Example: "CRITICAL"

AppHubWorkload

JSON representation 
{
  "id": string,
  "environmentType": string,
  "criticalityType": string
}
Fields
id

string

Workload Id. Example: "my-workload"
environmentType

string

Workload environment type Example: "DEV"
criticalityType

string

Workload criticality type Example: "CRITICAL"

Tool Annotations

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌