Skip to main content

Observability Migration Platform

Quality License & SBOM License: Elastic-2.0 Python 3.11+ PyPI

Migrate Grafana and Datadog dashboards, alerts, and monitors into Kibana. Unsupported translations are marked for manual review instead of being silently dropped.

You do not need to clone this repository. Install elastic-observability-migration from PyPI and run obs-migrate.

Requirements

Need Detail
OS macOS and Linux (Windows untested)
Python 3.11 or newer (tested on 3.11–3.13)
Installer uv on PATH (provides uv and uvx)
Kibana Elastic Serverless or Stack 9.5+

Install with the [all] extra so Grafana, Datadog, and Kibana tooling are available together.

Quick start

# Pin when you want a fixed release, e.g.
# PKG='elastic-observability-migration[all]==1.3.0'
PKG='elastic-observability-migration[all]'

uvx --from "$PKG" obs-migrate doctor
uvx --from "$PKG" obs-migrate list-samples

doctor exit code 0 means Ready; otherwise it prints what to fix.

Copy an input_dir path from the list-samples output and try an offline migrate:

uvx --from "$PKG" obs-migrate migrate \
  --source grafana --input-mode files \
  --input-dir "<input_dir from list-samples>" \
  --output-dir ./out --assets dashboards

Review the generated ./out/dashboards/native/*.native.json artifacts (the exact typed Dashboards API payloads), then upload:

uvx --from "$PKG" obs-migrate upload \
  --artifact-dir ./out/dashboards \
  --kibana-url "$KIBANA_ENDPOINT" \
  --kibana-api-key "$KEY"

For your own assets, use the same migrate command with exported JSON (--input-dir) or --input-mode api plus credentials. Upload, verification, index flags (--data-view / --esql-index), and the full flag reference: docs/command-contract.md.

Always reuse the same launcher as doctor (uvx --from "$PKG" …). PKG only lives in the shell you set it in, so re-export it in a new terminal.

If you see command not found: obs-migrate

obs-migrate is a console script, not a global binary: a bare obs-migrate only works when its install location is on PATH. Otherwise, prefix it with a launcher. Pick the line matching how you installed:

# uvx: works in any shell, nothing installed first (package spelled out in
# full, because a new shell has no variables from the Quick Start above)
uvx --from 'elastic-observability-migration[all]' obs-migrate doctor

# virtualenv, without activating it — relative path, so run it from the
# directory where you created the virtualenv
.venv/bin/obs-migrate doctor

# same virtualenv, activated once per shell — then the bare command works
source .venv/bin/activate && obs-migrate doctor

The last two need a .venv you already created — see Other install options — and both resolve .venv against your current directory, so cd there first or use the full path.

If you want a bare obs-migrate in every shell with no prefix, install it as a tool (uv tool install, or pipx install if you prefer pipx); that is the first option below. A tool install cannot put its shim directory on the PATH of the shell you run it in, so follow it with the export shown there.

Other install options

Persistent bare command — installs once and puts obs-migrate on PATH for every shell, so no launcher prefix is needed:

uv tool install 'elastic-observability-migration[all]'
export PATH="$HOME/.local/bin:$PATH"
obs-migrate doctor

uv tool install puts the shim in ~/.local/bin (uv tool dir --bin prints the real location) and warns when that directory is missing from PATH. It cannot change the PATH of the shell that invoked it, hence the export; run uv tool update-shell once so new shells pick it up too. pipx install works the same way. uv picks your newest Python, so add --python 3.13 to stay within the CI-tested range if your system Python is 3.14 or newer.

Persistent virtualenv (optional; prefer uvx above for first runs):

PKG='elastic-observability-migration[all]'
python3 -m venv .venv
.venv/bin/pip install "$PKG"
.venv/bin/obs-migrate doctor
# Or: source .venv/bin/activate && obs-migrate doctor

Narrower extras: [grafana], [datadog], or [kibana] instead of [all].

GitHub tag fallback (only if PyPI is unreachable; never @main):

PKG='elastic-observability-migration[all]@git+https://github.com/elastic/observability-migration-platform.git@v1.3.0'
uvx --from "$PKG" obs-migrate doctor

Dashboard upload goes through Kibana's typed Dashboards API and needs no external tooling: the kb-dashboard-* compile/lint path was removed, so there is no longer a Python 3.11 uvx-fallback requirement for dashboard work.

The older grafana-migrate and datadog-migrate commands remain as compatibility aliases. Prefer obs-migrate.

Documentation

Doc Use when
docs/command-contract.md Commands, flags, upload, and verification
docs/README.md Full docs index
docs/sources/grafana.md / datadog.md Source-specific behavior
docs/targets/kibana.md Kibana target behavior
SUPPORT.md Getting help
SECURITY.md Vulnerability reporting
CONTRIBUTING.md Repo checkout and contributor setup

Bugs and feature requests: open an issue.

Licensing

First-party content is source-available under the Elastic License 2.0 (ELv2); see LICENSE. Redistributed third-party material is listed in THIRD_PARTY_NOTICES.md.

Trademarks

Grafana is a trademark of Raintank, Inc. d/b/a Grafana Labs. Datadog is a trademark of Datadog, Inc. Prometheus and Kubernetes are trademarks of The Linux Foundation. Kibana and Elastic are trademarks of Elasticsearch B.V. All other trademarks are the property of their respective owners. Use of these names is solely for interoperability and identification and does not imply affiliation or endorsement.

Metadata

Release files for elastic-observability-migration 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for elastic-observability-migration 1.3.0
File Size Uploaded Provenance Actions
elastic_observability_migration-1.3.0.tar.gz 2.1 MB With provenance Details for elastic_observability_migration-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for elastic-observability-migration 1.3.0
File Interpreter ABI Platform Actions
elastic_observability_migration-1.3.0-py3-none-any.whl Python 3 none any Details for elastic_observability_migration-1.3.0-py3-none-any.whl

Total release size: 3.4 MB

Release files / elastic_observability_migration-1.3.0.tar.gz

Download URL elastic_observability_migration-1.3.0.tar.gz
Size 2.1 MB
Tags Source
SHA-256 checksum
How to use checksums
06d1b718e37739a5e744844da9b5acc9905646710120ea36e79180c44eec623d
BLAKE2b-256 checksum
How to use checksums
94628a04fed61b318626e88e3c6835436cddfa5d484626c7a15561ed9492a662
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / elastic_observability_migration-1.3.0-py3-none-any.whl

Download URL elastic_observability_migration-1.3.0-py3-none-any.whl
Size 1.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
ad8a0103b52cb5760a74569f03b5bb27fafb88da84bb5ab4f1ed451873b55dcb
BLAKE2b-256 checksum
How to use checksums
32fb7129cfa64110646c9f060455f8d2a9b9b196dc3aeb94d750052ecba1192d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for elastic-observability-migration 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for elastic_observability_migration-1.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page