logo

nsc instance report

Generates a report of compute instances.

instance report generates a CSV report of compute instances created in your workspace over a given time range. Each row describes a single instance, including its allocated and observed resource usage and, when applicable, the GitHub Actions job that triggered it.

The report contains the following columns:

  • instance_id
  • created_at, started_at, destroyed_at
  • resources_cpu, resources_ram_gb (allocated)
  • resources_cpu_actual_max, resources_ram_gb_actual_max_percent (observed)
  • github_job_id, github_job_name, github_job_workflow_name
  • github_run_id, github_run_attempt
  • job_created_at, job_started_at, job_completed_at
  • github_profile, github_repository, github_branch, github_job_conclusion

Usage

nsc instance report --start <time> [--end <time>] [--out <path>] [filters...]

--start is required. --end defaults to now if not provided. By default the report is written to a temporary file in /tmp; pass --out - to write to stdout, or --out <path> to write to a specific file.

Example

The following example generates a report covering the last hour and writes it to stdout:

$ nsc instance report --start 2026-05-11T11:00:00Z --out -
Writing output to path: stdout
instance_id,created_at,started_at,destroyed_at,resources_cpu,resources_ram_gb,resources_cpu_actual_max,resources_ram_gb_actual_max_percent,github_job_id,github_job_name,github_job_workflow_name,github_run_id,github_run_attempt,job_created_at,job_started_at,job_completed_at,github_profile,github_repository,github_branch,github_job_conclusion
iekjd1l47to3k,2026-05-11 12:09:57 +0000 UTC,2026-05-11 12:09:59 +0000 UTC,2026-05-11 12:11:10 +0000 UTC,8,16,0.7,0.17460646,75349817393,go test,Go,25669248595,1,2026-05-11 12:09:55 +0000 UTC,2026-05-11 12:10:05 +0000 UTC,2026-05-11 12:10:43 +0000 UTC,,namespacelabs/internal,main,success
mcja6q4oi4kh2,2026-05-11 12:09:57 +0000 UTC,2026-05-11 12:09:58 +0000 UTC,2026-05-11 12:12:07 +0000 UTC,16,32,0.6451724,0.14323927,75349827012,validate,Validate,25669251386,1,2026-05-11 12:09:59 +0000 UTC,2026-05-11 12:10:04 +0000 UTC,2026-05-11 12:11:29 +0000 UTC,,namespacelabs/internal,main,success
a5gkg10as2tdg,2026-05-11 12:09:57 +0000 UTC,2026-05-11 12:09:58 +0000 UTC,2026-05-11 12:10:46 +0000 UTC,2,4,0.94,0.2463041,75349817514,go lint,Go,25669248531,1,2026-05-11 12:09:55 +0000 UTC,2026-05-11 12:10:05 +0000 UTC,2026-05-11 12:10:22 +0000 UTC,,namespacelabs/internal,main,success

In the row above, instance iekjd1l47to3k was allocated 8 CPUs and 16 GiB of memory; during its lifetime it used at most 70% of the CPU and ~17% of the memory. It was created by the go test job of the Go workflow, GitHub run 25669248595.

To investigate resource optimization opportunities on Namespace, it can be useful to use nsc instance report in combination with an LLM agent:

Prompt

Based on GitHub job historical data over the last 7 days obtained via "nsc instance report", produce a short report of resource optimization opportunities for jobs (for the same job name, consistent low resource usage within a category)

Options

--start <time>

Start time of the report. Required.

--end <time>

End time of the report. Defaults to now if not provided.

--out <path>

Output file path. Creates a temporary file in /tmp if not provided. Use - for stdout.

--repository <repo>

GitHub repository (or repositories) to include in the report. Repeatable. Cannot be passed together with --exclude-repository.

--workflow <name>

GitHub workflow(s) to include in the report. Repeatable. Cannot be passed together with --exclude-workflow.

--jobname <name>

GitHub job name(s) to include in the report. Repeatable. Cannot be passed together with --exclude-jobname.

--branch <name>

GitHub branch(es) to include in the report. Repeatable. Cannot be passed together with --exclude-branch.

--platform <platform>

Platform(s) to include in the report (e.g. linux/amd64, linux/arm64). Repeatable. Cannot be passed together with --exclude-platform.

--shape <shape>

Instance shape(s) to include in the report. Repeatable. Cannot be passed together with --exclude-shape.

--purpose <purpose>

Instance purpose(s) to include in the report. Repeatable. Cannot be passed together with --exclude-purpose.

--profile <profile>

GitHub runner profile(s) to include in the report. Repeatable. Cannot be passed together with --exclude-profile.

--exclude-branch <name>

GitHub branch(es) to exclude from the report. Repeatable. Cannot be passed together with --branch.

--exclude-jobname <name>

GitHub job name(s) to exclude from the report. Repeatable. Cannot be passed together with --jobname.

--exclude-platform <platform>

Platform(s) to exclude from the report (e.g. linux/amd64, linux/arm64). Repeatable. Cannot be passed together with --platform.

--exclude-profile <profile>

GitHub runner profile(s) to exclude from the report. Repeatable. Cannot be passed together with --profile.

--exclude-purpose <purpose>

Instance purpose(s) to exclude from the report. Repeatable. Cannot be passed together with --purpose.

--exclude-repository <repo>

GitHub repository (or repositories) to exclude from the report. Repeatable. Cannot be passed together with --repository.

--exclude-shape <shape>

Instance shape(s) to exclude from the report. Repeatable. Cannot be passed together with --shape.

--exclude-workflow <name>

GitHub workflow(s) to exclude from the report. Repeatable. Cannot be passed together with --workflow.

These --exclude-* flags mirror their include counterparts above and form a consistent include/exclude filter family across the report's dimensions.

Last updated