Streaming logs (SDK)
Iterate Microtica build, deployment, and app logs as typed async streams with the SDK, including follow mode, search, and cancellation.
The SDK exposes logs as typed async streams. Build, deployment, and app logs all normalize to the same LogEntry shape, and every stream is an AsyncIterable<LogEntry> you consume with for await.
A stream comes from one of three namespace methods:
pipelines.buildLogs(...)— pipeline build outputenvs.deploymentLogs(...)— environment deployment eventsapps.logs(...)— Kubernetes pod logs
The LogEntry shape
Each entry is one normalized log line or event:
interface LogEntry {
timestamp: string; // ISO-8601
severity: "debug" | "info" | "warn" | "error";
source: "pipeline" | "deploy-cfn" | "deploy-tf" | "app-pod" | "service-fargate";
message: string;
step?: string; // pipeline source
resource?: string; // deploy-cfn source
status?: string; // deploy-cfn source — native CFN status, e.g. CREATE_FAILED
eventId?: string; // deploy-cfn source — de-dup key
}The source field tells you where an entry came from — useful when a single stream multiplexes more than one origin (a build step that stitches in its deployment events, for example).
Consume a stream
Iterate the stream, then call result() for the normalized terminal status once iteration ends:
const stream = microtica.pipelines.buildLogs(projectId, pipelineId, buildId);
for await (const entry of stream) {
console.log(`[${entry.severity}] ${entry.message}`);
}
const { normalized, statusRaw } = await stream.result();
// normalized: "success" | "failed" | "cancelled" | "interrupted"
// | "disconnected" | "timeout" | "unknown"Cancel a stream
Every stream option set takes an abortSignal. Use it to cancel follow mode on a timeout or a user interrupt:
const ac = new AbortController();
setTimeout(() => ac.abort(), 20 * 60_000); // give up after 20 minutes
const stream = microtica.envs.deploymentLogs(projectId, envId, deploymentId, {
follow: true,
abortSignal: ac.signal,
});
for await (const entry of stream) process.stdout.write(entry.message + "\n");Build logs
pipelines.buildLogs(projectId, pipelineId, buildId, opts?) streams a build's per-step output.
const stream = microtica.pipelines.buildLogs(projectId, pipelineId, buildId, {
follow: true,
});| Option | Description |
|---|---|
step | Stream a single step by name. Default: every step in order. |
raw | Send the unfiltered CloudWatch stream. |
follow | Stream until the build terminates. |
failuresOnly | Skip successful steps; mark failing steps' lines as errors. Not allowed with follow. |
stitch | Stitch a deploy step's CFN/Terraform events into the stream. Default true. |
pollIntervalMs | Build-status poll interval. Default 5000. |
abortSignal | Cancel the stream. |
Deployment logs
envs.deploymentLogs(projectId, envId, deploymentId, opts?) streams one deployment's events. It auto-routes by the environment's IaC tool: CloudFormation events for CFN environments, the realtime Terraform stream for Terraform ones.
const stream = microtica.envs.deploymentLogs(projectId, envId, deploymentId, {
follow: true,
onProgress: (phase) => process.stderr.write(`… ${phase}\n`),
});| Option | Description |
|---|---|
follow | Poll for new events until the deploy terminates. |
pollIntervalMs | Follow poll interval. Default 5000. |
onProgress | Hook called with progress phases during long pre-emission fetches. |
abortSignal | Cancel the stream. |
Get a deploymentId from envs.lastDeploy or pipelines.history.
App logs
apps.logs(projectId, name, opts?) returns a snapshot of a Kubernetes app's pod logs.
const stream = microtica.apps.logs(projectId, "api", { env: envId });
for await (const entry of stream) console.log(entry.message);| Option | Description |
|---|---|
env | Scope cluster/namespace resolution to one environment. |
pod | Pod name. Defaults to the first pod. |
cluster / namespace | Set cluster and namespace explicitly. |
abortSignal | Cancel the stream. |
App logs are a snapshot. follow and failuresOnly aren't supported for Kubernetes pod logs and throw a kind: "validation" error. Filter entries yourself, or use kubectl logs -f for a live tail.
Next steps
Git (SDK)
Read connected Git accounts, repositories, and branches with the SDK's git namespace to wire up pipelines and components programmatically.
Changelog
Release notes for Microtica â new features, template releases, monitoring and cost-optimization improvements, and platform changes, newest first.