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.4.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.4.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.4.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.4.0
File Size Uploaded Provenance Actions
elastic_observability_migration-1.4.0.tar.gz 2.1 MB With provenance Details for elastic_observability_migration-1.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 3.5 MB

Release files / elastic_observability_migration-1.4.0.tar.gz

Download URL elastic_observability_migration-1.4.0.tar.gz
Size 2.1 MB
Tags Source
SHA-256 checksum
How to use checksums
96d623ab27333761aadce741ec70b0a316e351dd4fa0ab79cde9c6dd34b81c11
BLAKE2b-256 checksum
How to use checksums
924b829ea7e2744bee4f1636e03638a2d8a86352735c6dc24b3447227fc74dfa
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 30, 2026.

Transparency log

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

Download URL elastic_observability_migration-1.4.0-py3-none-any.whl
Size 1.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
d614fc0ee9d58c0e45dbd1d8dbf6b4a25cf7b11631e98b31ce8753b3893095c7
BLAKE2b-256 checksum
How to use checksums
8c5c8eb7d14f94e3c372d6a2b8f7117a2d1f5a891e7ee10f60eb0b28596f5789
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 30, 2026.

Transparency log

Security for elastic-observability-migration 1.4.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.4.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 30, 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