Observability Migration Platform
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.