Read logs and egress records - Namespace Documentation

client.observability reads what an instance produced. Stream logs while an instance runs, fetch logs for a time range after the fact, or read the DNS egress records collected for an instance. Resource metrics and instance state notifications are served by the Compute service rather than the Observability service, so they are called on client.compute. They are documented here because they answer the same kind of question. See Compute observability for what the platform collects. The examples on this page use a Compute client:

import { createComputeClient } from "@namespacelabs/sdk/api/compute";

const client = createComputeClient();

`observability.streamInstanceLogs()`

Stream the logs of one instance. With follow set, the call waits for additional logs and terminates when the instance shuts down.

Example

for await (const block of client.observability.streamInstanceLogs({
  instanceId,
  follow: true,
})) {
  for (const line of block.lines) {
    console.log(line.stream, line.content);
  }
}

API reference

streamInstanceLogs(
  request: MessageInitShape<typeof StreamInstanceLogsRequestSchema>,
  options?: CallOptions,
): AsyncIterable<LogBlock>

Arguments and options

string

required

The instance to stream logs from.

boolean

When true, keeps the stream open and waits for new logs. The stream terminates when the instance shuts down.

StringMatcher

Only stream logs from matching containers.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns an async iterable of LogBlock. Each block batches lines from the same container to reduce bytes on the wire, so blocks from different containers can interleave.

Record<string, string>

Labels shared by every line in the block, such as the container the lines came from.

LogBlock_Line[]

The batched lines. Each has a timestamp, the line content, and the stream it came from, such as stdout or stderr.

Omitting the instance ID fails with InvalidArgument. An unknown instance ID fails with NotFound.

`observability.fetchInstanceLogs()`

Fetch logs for one or more instances over a time range. The instances can still be running.

Example

import { timestampFromDate } from "@bufbuild/protobuf/wkt";
import { StringMatcher_Operator } from "@namespacelabs/sdk/proto/namespace/stdlib/matchers_pb";

const page = await client.observability.fetchInstanceLogs({
  matchInstanceIds: {
    values: [instanceId],
    op: StringMatcher_Operator.IS_ANY_OF,
  },
  timestampRange: {
    after: timestampFromDate(new Date(Date.now() - 30 * 60 * 1000)),
    before: timestampFromDate(new Date()),
  },
  linesPerPage: 500,
});

for (const line of page.logLine) {
  console.log(line.timestamp, line.source, line.content);
}

API reference

fetchInstanceLogs(
  request: MessageInitShape<typeof FetchInstanceLogsRequestSchema>,
  options?: CallOptions,
): Promise<FetchInstanceLogsResponse>

Arguments and options

StringMatcher

The instances to fetch logs for.

TimestampRange

The time range to read, as after and before timestamps.

StringMatcher

Only return logs from matching containers.

number

The maximum number of lines to return per page.

Uint8Array

The paginationCursor from a previous response, to read the next page.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

A time range is required. Either query a naturally bounded range, such as the last 30 minutes, or look up when the instances ran and pass that range. Without one, the serving cost may be too high and the API can reject the call.

Return value

Returns a FetchInstanceLogsResponse.

LogLine[]

The matching lines. Each has a timestamp, content, the stream it came from, its labels, and a source such as containers, kubernetes, or kmsg.

Uint8Array

Pass this cursor to a subsequent call to read the next page.

number

How long logs are retained for the workspace, in days.

`compute.getInstanceMetrics()`

Return resource usage metrics for an instance. Metrics can be queried while the instance is still running.

Example

import { timestampFromDate } from "@bufbuild/protobuf/wkt";
import { GetInstanceMetricsRequest_MetricResource } from "@namespacelabs/sdk/proto/namespace/cloud/compute/v1beta/compute_pb";

const { timeSeries } = await client.compute.getInstanceMetrics({
  instanceId,
  startTimestamp: timestampFromDate(new Date(Date.now() - 60 * 60 * 1000)),
  metricResource: [
    GetInstanceMetricsRequest_MetricResource.CPU,
    GetInstanceMetricsRequest_MetricResource.MEMORY,
  ],
});

console.log(timeSeries.length);

API reference

getInstanceMetrics(
  request: MessageInitShape<typeof GetInstanceMetricsRequestSchema>,
  options?: CallOptions,
): Promise<GetInstanceMetricsResponse>

Arguments and options

string

required

The instance to read metrics for.

Timestamp

Only return metrics on or after this timestamp.

Timestamp

Only return metrics up to this timestamp.

MetricResource[]

Which metrics to return: CPU, CPU_BREAKDOWN, IO_WAIT, MEMORY, or STORAGE.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a GetInstanceMetricsResponse with timeSeries, one or more series carrying the requested metrics. Each series holds a shared timestamps array with named doubles, integers, and strings series aligned to it. If the instance does not exist, the call fails with NotFound.

`observability.fetchInstanceEgress()`

Fetch the egress records collected for an instance. Each record captures a resolved domain and the action that the egress policy applied.

Example

const page = await client.observability.fetchInstanceEgress({
  instanceId,
  limit: 1000,
});

for (const record of page.records) {
  console.log(record.timestamp, record.domain, record.action, record.ruleMatch);
}

API reference

fetchInstanceEgress(
  request: MessageInitShape<typeof FetchInstanceEgressRequestSchema>,
  options?: CallOptions,
): Promise<FetchInstanceEgressResponse>

Arguments and options

string

required

The instance to read egress records for.

TimestampRange

Restricts the records to a time range, as after and before timestamps.

number

default:"20000"

The maximum number of records to return.

Uint8Array

The paginationCursor from a previous response, to read the next page.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a FetchInstanceEgressResponse with records and a paginationCursor. Each EgressRecord carries:

Timestamp

When the request was observed.

string

The domain that was resolved.

EgressAction

The action applied: ALLOW, DENY, ADVISORY_DENY, or ACTION_UNKNOWN.

string

The rule matcher that led to the action, when one applied.

string[]

The IP addresses the domain resolved to.

`compute.listInstanceNotifications()`

List instance notification events. Each instance appears at most once, carrying its most recent state change.

Example

const { events } = await client.compute.listInstanceNotifications({
  onlyPendingEvents: true,
});

for (const event of events) {
  console.log(event.emittedAt, event.instanceId, event.status);
}

API reference

listInstanceNotifications(
  request: MessageInitShape<typeof ListInstanceNotificationsRequestSchema>,
  options?: CallOptions,
): Promise<ListInstanceNotificationsResponse>

Arguments and options

StringMatcher

Only return events for matching instances. When omitted, events for all instances are returned.

bigint

The maximum number of events to return. The response is always capped to an internal maximum as well.

boolean

When true, only returns pending events that have not yet been delivered.

CallOptions

Cancellation, timeout, and header options. See Shared call options.

Return value

Returns a ListInstanceNotificationsResponse with events, ordered by emitted time with the most recent first. Each InstanceEventMetadata carries emittedAt, instanceId, tenantId, the instance status, and its labels.

Compute observability

Logs, metrics, and instance debugging on the platform.

Egress policy

Control and audit outbound traffic from instances.

Run commands

Execute commands in a container on an instance.

​observability.streamInstanceLogs()

​Example

​API reference

​Arguments and options

​Return value

​observability.fetchInstanceLogs()

​Example

​API reference

​Arguments and options

​Return value

​compute.getInstanceMetrics()

​Example

​API reference

​Arguments and options

​Return value

​observability.fetchInstanceEgress()

​Example

​API reference

​Arguments and options

​Return value

​compute.listInstanceNotifications()

​Example

​API reference

​Arguments and options

​Return value

​Related documentation

Compute observability

Egress policy

Run commands

`observability.streamInstanceLogs()`

Example

API reference

Arguments and options

Return value

`observability.fetchInstanceLogs()`

Example

API reference

Arguments and options

Return value

`compute.getInstanceMetrics()`

Example

API reference

Arguments and options

Return value

`observability.fetchInstanceEgress()`

Example

API reference

Arguments and options

Return value

`compute.listInstanceNotifications()`

Example

API reference

Arguments and options

Return value

Related documentation