> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Read logs and egress records
> Stream and fetch instance logs, and read egress records, with the TypeScript SDK.
`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](/docs/architecture/compute/observability) for what the platform collects.
The examples on this page use a Compute client:
```typescript theme={null}
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
```typescript {1-4} theme={null}
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
```typescript theme={null}
streamInstanceLogs(
request: MessageInitShape,
options?: CallOptions,
): AsyncIterable
```
Arguments and options
The instance to stream logs from.
When `true`, keeps the stream open and waits for new logs. The stream terminates when the instance shuts down.
Only stream logs from matching containers.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#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.
Labels shared by every line in the block, such as the container the lines came from.
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
```typescript {4-12} theme={null}
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
```typescript theme={null}
fetchInstanceLogs(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
The instances to fetch logs for.
The time range to read, as `after` and `before` timestamps.
Only return logs from matching containers.
The maximum number of lines to return per page.
The `paginationCursor` from a previous response, to read the next page.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#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`.
The matching lines. Each has a `timestamp`, `content`, the `stream` it came from, its `labels`, and a `source` such as `containers`, `kubernetes`, or `kmsg`.
Pass this cursor to a subsequent call to read the next page.
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
```typescript {4-9} theme={null}
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
```typescript theme={null}
getInstanceMetrics(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
The instance to read metrics for.
Only return metrics on or after this timestamp.
Only return metrics up to this timestamp.
Which metrics to return: `CPU`, `CPU_BREAKDOWN`, `IO_WAIT`, `MEMORY`, or `STORAGE`.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#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](/docs/security/egress-policy) applied.
Example
```typescript {1-4} theme={null}
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
```typescript theme={null}
fetchInstanceEgress(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
The instance to read egress records for.
Restricts the records to a time range, as `after` and `before` timestamps.
The maximum number of records to return.
The `paginationCursor` from a previous response, to read the next page.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#shared-call-options).
Return value
Returns a `FetchInstanceEgressResponse` with `records` and a `paginationCursor`. Each `EgressRecord` carries:
When the request was observed.
The domain that was resolved.
The action applied: `ALLOW`, `DENY`, `ADVISORY_DENY`, or `ACTION_UNKNOWN`.
The rule matcher that led to the action, when one applied.
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
```typescript {1-3} theme={null}
const { events } = await client.compute.listInstanceNotifications({
onlyPendingEvents: true,
});
for (const event of events) {
console.log(event.emittedAt, event.instanceId, event.status);
}
```
API reference
```typescript theme={null}
listInstanceNotifications(
request: MessageInitShape,
options?: CallOptions,
): Promise
```
Arguments and options
Only return events for matching instances. When omitted, events for all instances are returned.
The maximum number of events to return. The response is always capped to an internal maximum as well.
When `true`, only returns pending events that have not yet been delivered.
Cancellation, timeout, and header options. See [Shared call options](/docs/reference/typescript-sdk/compute/manage#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`.
## Related documentation
Logs, metrics, and instance debugging on the platform.
Control and audit outbound traffic from instances.
Execute commands in a container on an instance.