Build Logs

Build logs capture detailed information about each bino build run, including timing, executed queries, generated artefacts, and optionally embedded data previews. They’re invaluable for debugging, auditing, and integrating bino into CI/CD pipelines.

Output Files

Every build produces at least a human-readable text log. When JSON features are enabled, a machine-readable JSON log is also generated:

File	Format	When Generated
`dist/bino-build-<id>.log`	Text	Always
`dist/bino-build-<id>.json`	JSON	When `--build-log-format=json` or `--embed-data-csv` is used

The <id> is a unique identifier (hash) for each build run.

Text Log Format

The text log (*.log) provides a human-readable summary of the build:

bino build started at 2025-01-15T10:30:00Z
Workdir: /path/to/project

=== Documents ===
  [1] report.yaml (kind: report, name: monthly-sales)
  [2] datasources/sales.yaml (kind: datasource, name: sales_db)

=== Artefacts ===
  monthly-sales → dist/monthly-sales.pdf

=== Queries ===
  [query-001] SELECT * FROM sales WHERE month = 1
    Duration: 45ms | Rows: 1,234

Build completed in 2.5s

This format is optimized for quick visual inspection in terminals and log viewers.

JSON Log Format

The JSON log (*.json) provides structured, machine-readable build data suitable for programmatic analysis, CI/CD integration, and debugging tools.

When It’s Generated

The JSON log is written when you use:

--build-log-format=json - Explicitly request JSON output
--embed-data-csv - CSV embedding requires JSON format

JSON Schema Overview

{
  "run_id": "e7d7742d",
  "started": "2025-01-15T10:30:00Z",
  "completed": "2025-01-15T10:30:02.5Z",
  "duration_ms": 2500,
  "workdir": "/path/to/project",
  "documents": [
    {
      "file": "report.yaml",
      "position": 1,
      "kind": "report",
      "name": "monthly-sales"
    }
  ],
  "artefacts": [
    {
      "name": "monthly-sales",
      "pdf": "dist/monthly-sales.pdf",
      "graph": "dist/monthly-sales.pdf.bngraph"
    }
  ],
  "queries": [
    {
      "id": "query-001",
      "query": "SELECT * FROM sales WHERE month = 1",
      "query_type": "dataset",
      "dataset": "sales_summary",
      "start_time": "2025-01-15T10:30:00.5Z",
      "duration_ms": 45,
      "row_count": 1234,
      "columns": ["id", "product", "amount"],
      "csv": { ... }
    }
  ],
  "execution_plan": [ ... ]
}

graph is the PDF path with .bngraph appended. The file is a plain text table of the artefact’s dependency graph (columns KIND, NAME, HASH, DEPENDS ON, DETAILS), the flat view of bino graph, not a Graphviz file.

CSV Data Embedding

Embed query result previews directly in your build logs for data auditing and debugging. This feature captures the first N rows of each query result as CSV data.

Enabling CSV Embedding

bino build --embed-data-csv

This automatically enables JSON log output and embeds CSV previews in each query entry.

Configuration Options

Flag	Default	Description
`--embed-data-csv`	`false`	Enable CSV data embedding
`--embed-data-max-rows`	`10`	Maximum rows to capture per query
`--embed-data-max-bytes`	`65536`	Maximum bytes per CSV blob (64 KB)
`--embed-data-base64`	`true`	Base64 encode CSV data
`--embed-data-redact`	`true`	Redact sensitive column values

CSV Result Structure

When embedded, each query includes a csv field:

{
  "id": "query-001",
  "query": "SELECT id, email, api_key FROM users LIMIT 5",
  "csv": {
    "encoding": "base64",
    "mime_type": "text/csv",
    "bytes": 156,
    "rows": 5,
    "truncated": false,
    "data": "aWQsZW1haWwsYXBpX2tleQoxLGFsaWNlQGV4YW1wbGUuY29tLFtSRURBQ1RFRF0K..."
  }
}

Security: Automatic Redaction

When --embed-data-redact is enabled (default), columns matching sensitive patterns are automatically replaced with [REDACTED]:

Redacted patterns include:

password, passwd
secret, token, key, api_key
private, credential, auth

Example:

id,email,api_key
1,alice@example.com,[REDACTED]
2,bob@example.com,[REDACTED]

Truncation Behavior

Data is truncated when:

Row count exceeds --embed-data-max-rows
Byte size exceeds --embed-data-max-bytes

When truncated, the truncated field is set to true.

Detailed Execution Plan

Track step-by-step timing of build phases for performance analysis and debugging.

Enabling Execution Plan

bino build --detailed-execution-plan

This adds an execution_plan array to the JSON log.

Tracked Steps

Step Name	Description
`load_manifests`	Loading and parsing YAML manifest files
`validate_manifests`	Validating manifest schemas and references
`build_graph`	Building the dependency graph
`collect_datasources`	Connecting to and introspecting datasources
`execute_datasets`	Running SQL queries for datasets
`render_html`	Rendering HTML templates
`generate_pdf`	Converting HTML to PDF via rendering engine
`sign_pdf`	Signing PDF with digital certificates
`write_outputs`	Writing final output files

Execution Step Structure

{
  "execution_plan": [
    {
      "id": "step-001",
      "name": "load_manifests",
      "phase": "global",
      "start_time": "2025-01-15T10:30:00.1Z",
      "end_time": "2025-01-15T10:30:00.15Z",
      "duration_ms": 50,
      "status": "completed"
    },
    {
      "id": "step-005",
      "name": "execute_datasets",
      "phase": "artefact:monthly-sales",
      "start_time": "2025-01-15T10:30:00.5Z",
      "end_time": "2025-01-15T10:30:01.2Z",
      "duration_ms": 700,
      "status": "completed",
      "details": "Executed 5 queries"
    }
  ]
}

Interpreting Timing Data

phase: Either "global" for overall build steps, or "artefact:<name>" for per-artefact steps
status: One of "running", "completed", "failed", or "skipped"
duration_ms: Elapsed time in milliseconds
error: Present only when status is "failed"

CLI Reference

Log Format Flags

Flag	Type	Default	Description
`--build-log-format`	string	`"text"`	Build log format: `"text"` or `"json"`
`--detailed-execution-plan`	bool	`false`	Include step-by-step timing in JSON log

CSV Embedding Flags

Flag	Type	Default	Description
`--embed-data-csv`	bool	`false`	Enable CSV data embedding (implies JSON log)
`--embed-data-max-rows`	int	`10`	Maximum rows per query preview
`--embed-data-max-bytes`	int	`65536`	Maximum bytes per CSV blob
`--embed-data-base64`	bool	`true`	Base64 encode CSV data
`--embed-data-redact`	bool	`true`	Redact sensitive column values

Examples

Basic JSON Log

Generate a machine-readable JSON log alongside the text log:

bino build --build-log-format=json

Full Debugging Output

Capture everything-JSON format, embedded data previews, and execution timing:

bino build --build-log-format=json --embed-data-csv --detailed-execution-plan

Custom CSV Limits

Embed more rows with larger size limit:

bino build --embed-data-csv --embed-data-max-rows=50 --embed-data-max-bytes=131072

Disable Redaction (Use with Caution)

bino build --embed-data-csv --embed-data-redact=false

CI/CD Integration

GitHub Actions

- name: Build Reports
  run: bino build --build-log-format=json --detailed-execution-plan

- name: Upload Build Artifacts
  uses: actions/upload-artifact@v4
  with:
    name: reports
    path: |
      dist/*.pdf
      dist/*.json
      dist/*.log

GitLab CI

build:
  script:
    - bino build --build-log-format=json --detailed-execution-plan
  artifacts:
    paths:
      - dist/*.pdf
      - dist/*.json
      - dist/*.log
    expire_in: 1 week

Parsing JSON Logs

Use jq to extract information from JSON logs:

# Get total build duration
jq '.duration_ms' dist/bino-build-*.json

# List all queries with their durations
jq '.queries[] | {id, duration_ms, row_count}' dist/bino-build-*.json

# Find slow queries (>100ms)
jq '.queries[] | select(.duration_ms > 100) | {id, query, duration_ms}' dist/bino-build-*.json

# Get execution plan summary
jq '.execution_plan[] | {name, phase, duration_ms, status}' dist/bino-build-*.json