fix: stabilize history timestamps and telemetry docs (#100)

* fix: stabilize history timestamps and telemetry docs

* fix: preserve numeric epoch cursors in history SQLite queries

Normalize mixed ISO and unixepoch time values for incremental resume and scoped dedup so legacy numeric rows are not dropped by julianday filters.

Co-authored-by: Cursor <cursoragent@cursor.com>

* Bump version to v1.1.2

* fix: aggregate incremental start timestamps in SQLite

Use MAX on the normalized time expression with GROUP BY so incremental
resume loaders stay O(groups) instead of materializing every history row.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test: parametrize duplicated incremental-start cases in TestIncrementalStart

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/api/grafana.md

@@ -0,0 +1,25 @@
+# Grafana
+
+::: mt5cli.grafana
+
+## Grafana-ready SQLite workflow
+
+Use `ensure_grafana_schema(conn)` or the `grafana-schema` CLI command to create
+the snapshot tables, `grafana_*` views, and supporting indexes in one step.
+
+`publish_grafana_copy(source, target)` creates a consistent SQLite copy via the
+SQLite backup API, which is useful when the primary database is running in WAL
+mode and Grafana should read from a separate published file.
+
+## Main APIs
+
+- `ensure_grafana_schema()`: idempotently creates snapshot tables, Grafana
+  views, and indexes.
+- `create_grafana_views()`: rebuilds the shipped `grafana_*` views.
+- `create_grafana_indexes()`: creates read-oriented indexes for Grafana
+  queries.
+- `publish_grafana_copy()`: writes an atomic, WAL-safe published copy for a
+  Grafana datasource.
+
+For end-to-end snapshot collection examples, see the Grafana and observability
+section in the project `README.md`.

docs/api/index.md

@@ -18,6 +18,8 @@ responsibilities.
 | [SDK](sdk.md)                             | Module-level fetch helpers, multi-account collectors, incremental history |
 | [Trading](trading.md)                     | Trading-capable sessions and operational helpers                          |
 | [History Collection (SQLite)](history.md) | SQLite schema, incremental writes, dedup, and rate views                  |
+| [Telemetry](telemetry.md)                 | OpenTelemetry metrics setup, meters, and emitted metric names             |
+| [Grafana](grafana.md)                     | Grafana-ready SQLite schema, views, snapshots, and published copies       |
 | [CLI](cli.md)                             | Typer commands that delegate to the Python API                            |
 | [Utils](utils.md)                         | Parsing helpers and Click parameter types                                 |
 

docs/api/telemetry.md

@@ -0,0 +1,50 @@
+# Telemetry
+
+::: mt5cli.telemetry
+
+## Enabling OpenTelemetry metrics
+
+Install the optional exporter dependencies with:
+
+```bash
+uv add 'mt5cli[otel]'
+```
+
+Then enable the default OTLP HTTP pipeline:
+
+```python
+from mt5cli.telemetry import enable_otel_metrics
+
+enable_otel_metrics(service_name="mt5cli")
+```
+
+When `readers=None`, `enable_otel_metrics()` builds a
+`PeriodicExportingMetricReader` backed by the OTLP HTTP exporter and reads the
+endpoint from `OTEL_EXPORTER_OTLP_ENDPOINT`.
+
+If your application already owns an OpenTelemetry `Meter`, wire mt5cli into it
+directly with `configure_metrics(meter)`.
+
+## Emitted metric names
+
+`enable_otel_metrics()` / `configure_metrics()` register these instruments:
+
+- `mt5_history_update_duration_seconds`
+- `mt5_history_update_rows_total`
+- `mt5_history_update_failures_total`
+- `mt5_snapshot_update_duration_seconds`
+- `mt5_snapshot_update_failures_total`
+- `mt5_account_balance`
+- `mt5_account_equity`
+- `mt5_account_margin`
+- `mt5_account_margin_free`
+- `mt5_account_margin_level`
+- `mt5_position_profit`
+- `mt5_position_volume`
+- `mt5_terminal_connected`
+- `mt5_terminal_trade_allowed`
+- `mt5_terminal_trade_expert`
+- `mt5_last_successful_update_timestamp`
+
+The history metrics use a `dataset` attribute. Account and position gauges add
+labels such as `login`, `server`, and `symbol` where applicable.