# SDK logging

Create a run at the start of your script, log metrics inside the loop, and
finish the run when the script ends.

## Create a run

```python
import instantml as im

run = im.init(
    project="mnist",
    name="cnn-seed-7",
    config={"seed": 7, "optimizer": "adam"},
    tags=["baseline"],
    notes="First CNN baseline.",
)
```

Both `project` and `name` are optional:

| Field | Default when omitted | Notes |
| --- | --- | --- |
| `project` | `"default"` | A shared bucket. The project is created on first use. |
| `name` | `<adjective>-<noun>-<sequence>` | Assigned by the server, e.g. `bold-falcon-1`. The adjective/noun pair is picked at random per create; the sequence is the run's 1-indexed position in its project. |

The auto-name is assigned server-side and shown in the dashboard; the run
handle does not expose it. Use `run.run_id` when a script needs a stable
identifier:

```python
run = im.init()
print(run.run_id)
```

Pass an explicit `name=` whenever the run is meaningful long-term, such as a
sweep cell or experiment cohort. The auto-name is for quick iteration and
smoke tests.

Use `im.Client(...)` when you want to reuse a base URL, timeout, or API key
across several runs:

```python
client = im.Client(
    base_url="https://api.instantml.ai",
    timeout=2.0,
    api_key="instantml_...",
)

run = client.init(project="cartpole", name="ppo-seed-42")
```

## Log scalar metrics

`run.log(...)` is the ergonomic API. If `step` is omitted, the SDK
auto-increments from `1`. If `step` is provided, it uses that value and
advances the implicit counter to at least that step.

```python
run.log({"train/reward": 100.0})
run.log({"train/loss": 0.12, "eval/accuracy": 0.91}, step=2)
```

Metric steps must be finite, nonnegative numbers. The UI expects each metric's
step values to move forward over time. See
[Metrics and steps](/docs/sdk/metrics-steps.md) for naming and batching guidance.

## Add run context

```python
run.log_config({"optimizer": {"lr": 0.0003}})
run.add_tags(["ready-for-compare"])
run.set_notes("Reward improved but entropy dipped late.")
```

Configs appear in Run Detail and Compare. Tags and notes are searchable in the
run list and editable from the dashboard.

## Finish cleanly

```python
run.finish()
```

You can also use a context manager:

```python
with im.init(project="mnist", name="cnn-seed-7", config={"seed": 7}) as run:
    run.log({"train/loss": 0.42}, step=1)
```

If the block exits normally, the SDK finishes the run as `finished`. If an
exception escapes the block, the SDK marks it as `failed`.

By default, run creation starts in the background so training scripts avoid
waiting on startup. Call `run.wait_for_init()` before expensive work when you
want credential or connectivity failures to surface immediately.

## Choose an upload mode

The default async mode queues writes locally and drains them in the
background. For batching, offline replay, or process-isolated spooling, see
[Buffering, offline replay, and spool mode](/docs/sdk/reliability.md).

## Next steps

- [Metrics and steps](/docs/sdk/metrics-steps.md) — metric naming, steps, and batching
- [Configs, tags, and notes](/docs/sdk/config-tags-notes.md) — make runs searchable
- [Buffering, offline replay, and spool mode](/docs/sdk/reliability.md) — durable upload modes
- [Artifacts and checkpoints](/docs/sdk/artifacts-checkpoints.md) — upload files and checkpoints
- [Query runs and metrics](/docs/sdk/querying-data.md) — read runs back from scripts

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md)
- [Logging](/docs/sdk/logging.md) (current page)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md)
- [Schema Reference](/docs/architecture/schema-reference.md)

### API Reference

- [API Reference](/docs/api-reference.md)