Skip to content

Diagnose a run

Use log messages to see what portolan-cli does, and timings to see where a run spends its time and memory. Both write to stderr or to a file. Stdout keeps the normal output, so a script that parses --format json output still works.

Log messages

By default, portolan-cli prints warnings and errors to stderr. Put a verbosity flag before the command name:

Flag Level Loggers
none WARNING all
-v INFO portolan_cli
-vv DEBUG portolan_cli, urllib3, httpx, and obstore
-q, --quiet ERROR all
portolan -vv add demographics/

Each line shows the seconds since start, the level, and the logger name:

+0.412s DEBUG portolan_cli.add: ...

At -vv, Python warnings also go through the log as the py.warnings logger.

Some commands, such as check, add, and readme, have their own --verbose flag. That flag controls how much the command prints, and the root flag controls the log level. portolan -v check --verbose sets both.

These environment variables also control logging:

Variable Effect
PORTOLAN_LOG Sets the level to debug, info, or warning when you give no flag. A flag takes precedence.
PORTOLAN_LOG_FILE Also writes each record to this path as one JSON object per line, with the run ID.
PORTOLAN_GDAL_DEBUG Set to 1 to turn on GDAL debug output (CPL_DEBUG=ON). The GDAL messages go to stderr as rasterio._env records at any verbosity.

Timings

Timings are off by default. To turn them on, set PORTOLAN_TIMINGS=1 or pass --timings before the command name:

portolan --timings add demographics/

In text mode, a table of the stages prints to stderr when the command exits:

span                  wall s  cpu s  rss MB
portolan.add           4.210  5.902   412.3
  add.collect          0.031  0.030   188.0
  add.process          3.104  4.880   412.3

Wall time is elapsed time. CPU time is the CPU time of the whole process, worker threads included. rss MB is the resident memory high-water mark of the process at the end of the stage.

PORTOLAN_TIMINGS=mem also records the Python memory growth of each stage with tracemalloc. The growth is the peak traced memory of the stage less the traced memory when the stage starts. Memory that an earlier stage holds does not count. This mode makes the run slower.

The meta block

With timings on, JSON output gets a meta key next to data. The error envelope gets it too. Without timings, the envelope has no meta key.

PORTOLAN_TIMINGS=1 portolan --format json add demographics/
Field Holds
timings The span tree. Each span has name, start_s, wall_s, cpu_s, rss_peak_mb, tid, attrs, and children.
counters Counts of repeated work for the whole run.
peak_rss_mb The resident memory high-water mark of the process.
version The portolan-cli version.
run_id The ID that also appears in PORTOLAN_LOG_FILE records.

The envelope prints before the command span closes, so that span has "open": true and its duration stops at the print. In mem mode, each span also has mem_growth_mb. tracemalloc traces the whole process, so this value also holds the memory that other threads allocate while the span is open.

The counters are:

Counter Counts
checksum.files, checksum.bytes Files and bytes hashed with SHA-256
versions_json.reads Reads of a local or remote versions.json
versions_json.writes Writes of a versions.json file
collection_json.writes Writes of a collection.json file
items_parquet.writes Builds of a collection items.parquet
config.yaml_parses Parses of a config.yaml or metadata.yaml file
config.merges Merges of the config.yaml or metadata.yaml hierarchy of a directory
versions.published Versions that the run publishes
versions.asset_maps Conversions of the current assets of a versions.json for lookup
thumbnail.draws Full draws of a vector thumbnail figure
tiles.fetched Basemap tiles that a vector thumbnail downloads
raster.opens Rasters opened for reading
parquet.opens Parquet files opened for reading
vector.opens Other vector files opened for reading, such as FlatGeobuf
duckdb.connects DuckDB connections. Only the perf harness in tests/perf counts them

Trace files

Set PORTOLAN_TRACE_FILE to write the spans as a Chrome trace. This variable also turns timings on.

PORTOLAN_TRACE_FILE=trace.json portolan add demographics/

Open the file in Perfetto. Each thread gets its own row. The rows show how the worker threads of add, push, and extract overlap.

Limits

  • Windows has no resource module, so rss_peak_mb is null there.
  • With more than one worker, check --fix converts files in worker processes. Spans and counters inside those processes do not reach the parent run.
  • rashid runs all validation rules in one call, so check.validate is one span for all the rules.
  • In mem mode, the tracemalloc peak is for the whole process. With more than one worker, the peak of a span can include memory that other threads allocated.