obskitpy 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- obskitpy-0.1.0/LICENSE +21 -0
- obskitpy-0.1.0/PKG-INFO +98 -0
- obskitpy-0.1.0/README.md +66 -0
- obskitpy-0.1.0/pyproject.toml +48 -0
- obskitpy-0.1.0/setup.cfg +4 -0
- obskitpy-0.1.0/src/obskitpy/__init__.py +122 -0
- obskitpy-0.1.0/src/obskitpy/cli.py +178 -0
- obskitpy-0.1.0/src/obskitpy/dashboard.py +177 -0
- obskitpy-0.1.0/src/obskitpy/errors.py +24 -0
- obskitpy-0.1.0/src/obskitpy/kibana.py +51 -0
- obskitpy-0.1.0/src/obskitpy/templates/__init__.py +0 -0
- obskitpy-0.1.0/src/obskitpy/templates/docker-compose.yml +40 -0
- obskitpy-0.1.0/src/obskitpy/templates/otel-collector-config.yaml +24 -0
- obskitpy-0.1.0/src/obskitpy.egg-info/PKG-INFO +98 -0
- obskitpy-0.1.0/src/obskitpy.egg-info/SOURCES.txt +18 -0
- obskitpy-0.1.0/src/obskitpy.egg-info/dependency_links.txt +1 -0
- obskitpy-0.1.0/src/obskitpy.egg-info/entry_points.txt +2 -0
- obskitpy-0.1.0/src/obskitpy.egg-info/requires.txt +10 -0
- obskitpy-0.1.0/src/obskitpy.egg-info/top_level.txt +1 -0
- obskitpy-0.1.0/tests/test_obskitpy.py +60 -0
obskitpy-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pedro França
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
obskitpy-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: obskitpy
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Observabilidade (OpenTelemetry + Elasticsearch + Kibana) para qualquer projeto Python, via CLI.
|
|
5
|
+
Author: Pedro França
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/pedrowill-dev/obskitpy
|
|
8
|
+
Project-URL: Documentation, https://github.com/pedrowill-dev/obskitpy/tree/main/docs
|
|
9
|
+
Project-URL: Issues, https://github.com/pedrowill-dev/obskitpy/issues
|
|
10
|
+
Keywords: observability,opentelemetry,elasticsearch,kibana,rpa,logging,tracing
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: System :: Monitoring
|
|
19
|
+
Classifier: Topic :: System :: Logging
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: opentelemetry-api==1.27.0
|
|
24
|
+
Requires-Dist: opentelemetry-sdk==1.27.0
|
|
25
|
+
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc==1.27.0
|
|
26
|
+
Provides-Extra: requests
|
|
27
|
+
Requires-Dist: opentelemetry-instrumentation-requests==0.48b0; extra == "requests"
|
|
28
|
+
Requires-Dist: setuptools==75.6.0; extra == "requests"
|
|
29
|
+
Provides-Extra: test
|
|
30
|
+
Requires-Dist: pytest; extra == "test"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
<p align="center"><img src="https://raw.githubusercontent.com/pedrowill-dev/obskitpy/main/docs/images/logo.png" alt="obskitpy" width="380"></p>
|
|
34
|
+
|
|
35
|
+
# obskitpy
|
|
36
|
+
|
|
37
|
+
Observabilidade (OpenTelemetry → Elasticsearch → Kibana) em qualquer projeto Python, via CLI.
|
|
38
|
+
|
|
39
|
+
> Documentação completa na raiz do repositório: [`docs/`](../docs/inicio-rapido.md). Este arquivo é um resumo.
|
|
40
|
+
|
|
41
|
+
## Começar (2 comandos)
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
uv add "obskitpy[requests]" # ou pip install; o extra 'requests' adiciona spans HTTP automáticos
|
|
45
|
+
cd meu-projeto
|
|
46
|
+
obskitpy init # cria observability/ (stack + dashboard base); --service NOME opcional
|
|
47
|
+
obskitpy up # sobe ES + Kibana + Collector e cria o dashboard
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
No código:
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
import logging, obskitpy
|
|
54
|
+
|
|
55
|
+
log = logging.getLogger(__name__)
|
|
56
|
+
shutdown = obskitpy.setup("meu-servico") # logs + traces + métricas via OTLP (localhost:4317)
|
|
57
|
+
|
|
58
|
+
@obskitpy.traced() # um span por chamada, marca erro se a exceção propagar
|
|
59
|
+
def processar(item): ...
|
|
60
|
+
|
|
61
|
+
try:
|
|
62
|
+
processar(x)
|
|
63
|
+
except Exception:
|
|
64
|
+
log.exception("falhou") # já sai com error.type, error.origin e error.chain
|
|
65
|
+
|
|
66
|
+
shutdown() # descarrega os dados pendentes
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Métricas próprias: `obskitpy.meter().create_counter("pedidos.processados")` (API do OpenTelemetry).
|
|
70
|
+
|
|
71
|
+
## Comandos
|
|
72
|
+
|
|
73
|
+
| Comando | O que faz |
|
|
74
|
+
|---|---|
|
|
75
|
+
| `obskitpy init [--service N] [--kibana-port P ...]` | cria `observability/` (compose, collector, `dashboard.ndjson`, `.env`) |
|
|
76
|
+
| `obskitpy up` | sobe a stack, espera ficar saudável e **aplica o dashboard** |
|
|
77
|
+
| `obskitpy down [-v]` | derruba (`-v` apaga os dados) |
|
|
78
|
+
| `obskitpy status` / `obskitpy open` | containers + link / abre o dashboard |
|
|
79
|
+
| `obskitpy dashboard export` | grava no arquivo o dashboard **como está no Kibana** |
|
|
80
|
+
| `obskitpy dashboard apply` | importa `observability/dashboard.ndjson` no Kibana |
|
|
81
|
+
|
|
82
|
+
Todos aceitam `--dir` (padrão `observability`).
|
|
83
|
+
|
|
84
|
+
## Evoluindo o dashboard
|
|
85
|
+
|
|
86
|
+
1. `obskitpy up` já cria o dashboard `<servico>-observability` com os painéis básicos: logs, erros, execuções (traces), duração de spans, erros por tipo/origem e lista de erros com `trace_id`.
|
|
87
|
+
2. Edite no Kibana (adicione painéis, métricas do seu domínio, filtros).
|
|
88
|
+
3. `obskitpy dashboard export` e versione `observability/dashboard.ndjson` no git.
|
|
89
|
+
4. Em outra máquina/CI: `obskitpy up` (ou `obskitpy dashboard apply`) recria tudo.
|
|
90
|
+
|
|
91
|
+
Os painéis filtram por `resource.attributes.service.name`, então vários serviços podem compartilhar uma stack (use o mesmo `--dir`/portas) ou ter uma cada (use portas diferentes no `init`).
|
|
92
|
+
|
|
93
|
+
## Observações
|
|
94
|
+
|
|
95
|
+
- Ambiente local: segurança do Elasticsearch desligada, portas só em `127.0.0.1`.
|
|
96
|
+
- Os dados demoram alguns segundos para ficar pesquisáveis após o primeiro envio.
|
|
97
|
+
- Colima/Docker: o `docker compose` precisa enxergar a pasta do projeto (no Colima, só `$HOME` é montado por padrão).
|
|
98
|
+
- Requer Docker com o plugin Compose v2.
|
obskitpy-0.1.0/README.md
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
<p align="center"><img src="https://raw.githubusercontent.com/pedrowill-dev/obskitpy/main/docs/images/logo.png" alt="obskitpy" width="380"></p>
|
|
2
|
+
|
|
3
|
+
# obskitpy
|
|
4
|
+
|
|
5
|
+
Observabilidade (OpenTelemetry → Elasticsearch → Kibana) em qualquer projeto Python, via CLI.
|
|
6
|
+
|
|
7
|
+
> Documentação completa na raiz do repositório: [`docs/`](../docs/inicio-rapido.md). Este arquivo é um resumo.
|
|
8
|
+
|
|
9
|
+
## Começar (2 comandos)
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
uv add "obskitpy[requests]" # ou pip install; o extra 'requests' adiciona spans HTTP automáticos
|
|
13
|
+
cd meu-projeto
|
|
14
|
+
obskitpy init # cria observability/ (stack + dashboard base); --service NOME opcional
|
|
15
|
+
obskitpy up # sobe ES + Kibana + Collector e cria o dashboard
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
No código:
|
|
19
|
+
|
|
20
|
+
```python
|
|
21
|
+
import logging, obskitpy
|
|
22
|
+
|
|
23
|
+
log = logging.getLogger(__name__)
|
|
24
|
+
shutdown = obskitpy.setup("meu-servico") # logs + traces + métricas via OTLP (localhost:4317)
|
|
25
|
+
|
|
26
|
+
@obskitpy.traced() # um span por chamada, marca erro se a exceção propagar
|
|
27
|
+
def processar(item): ...
|
|
28
|
+
|
|
29
|
+
try:
|
|
30
|
+
processar(x)
|
|
31
|
+
except Exception:
|
|
32
|
+
log.exception("falhou") # já sai com error.type, error.origin e error.chain
|
|
33
|
+
|
|
34
|
+
shutdown() # descarrega os dados pendentes
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Métricas próprias: `obskitpy.meter().create_counter("pedidos.processados")` (API do OpenTelemetry).
|
|
38
|
+
|
|
39
|
+
## Comandos
|
|
40
|
+
|
|
41
|
+
| Comando | O que faz |
|
|
42
|
+
|---|---|
|
|
43
|
+
| `obskitpy init [--service N] [--kibana-port P ...]` | cria `observability/` (compose, collector, `dashboard.ndjson`, `.env`) |
|
|
44
|
+
| `obskitpy up` | sobe a stack, espera ficar saudável e **aplica o dashboard** |
|
|
45
|
+
| `obskitpy down [-v]` | derruba (`-v` apaga os dados) |
|
|
46
|
+
| `obskitpy status` / `obskitpy open` | containers + link / abre o dashboard |
|
|
47
|
+
| `obskitpy dashboard export` | grava no arquivo o dashboard **como está no Kibana** |
|
|
48
|
+
| `obskitpy dashboard apply` | importa `observability/dashboard.ndjson` no Kibana |
|
|
49
|
+
|
|
50
|
+
Todos aceitam `--dir` (padrão `observability`).
|
|
51
|
+
|
|
52
|
+
## Evoluindo o dashboard
|
|
53
|
+
|
|
54
|
+
1. `obskitpy up` já cria o dashboard `<servico>-observability` com os painéis básicos: logs, erros, execuções (traces), duração de spans, erros por tipo/origem e lista de erros com `trace_id`.
|
|
55
|
+
2. Edite no Kibana (adicione painéis, métricas do seu domínio, filtros).
|
|
56
|
+
3. `obskitpy dashboard export` e versione `observability/dashboard.ndjson` no git.
|
|
57
|
+
4. Em outra máquina/CI: `obskitpy up` (ou `obskitpy dashboard apply`) recria tudo.
|
|
58
|
+
|
|
59
|
+
Os painéis filtram por `resource.attributes.service.name`, então vários serviços podem compartilhar uma stack (use o mesmo `--dir`/portas) ou ter uma cada (use portas diferentes no `init`).
|
|
60
|
+
|
|
61
|
+
## Observações
|
|
62
|
+
|
|
63
|
+
- Ambiente local: segurança do Elasticsearch desligada, portas só em `127.0.0.1`.
|
|
64
|
+
- Os dados demoram alguns segundos para ficar pesquisáveis após o primeiro envio.
|
|
65
|
+
- Colima/Docker: o `docker compose` precisa enxergar a pasta do projeto (no Colima, só `$HOME` é montado por padrão).
|
|
66
|
+
- Requer Docker com o plugin Compose v2.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=75"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "obskitpy"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Observabilidade (OpenTelemetry + Elasticsearch + Kibana) para qualquer projeto Python, via CLI."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
authors = [{ name = "Pedro França" }]
|
|
12
|
+
keywords = ["observability", "opentelemetry", "elasticsearch", "kibana", "rpa", "logging", "tracing"]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Development Status :: 4 - Beta",
|
|
15
|
+
"Intended Audience :: Developers",
|
|
16
|
+
"Programming Language :: Python :: 3",
|
|
17
|
+
"Programming Language :: Python :: 3.10",
|
|
18
|
+
"Programming Language :: Python :: 3.11",
|
|
19
|
+
"Programming Language :: Python :: 3.12",
|
|
20
|
+
"Programming Language :: Python :: 3.13",
|
|
21
|
+
"Topic :: System :: Monitoring",
|
|
22
|
+
"Topic :: System :: Logging",
|
|
23
|
+
]
|
|
24
|
+
license = "MIT"
|
|
25
|
+
license-files = ["LICENSE"]
|
|
26
|
+
dependencies = [
|
|
27
|
+
"opentelemetry-api==1.27.0",
|
|
28
|
+
"opentelemetry-sdk==1.27.0",
|
|
29
|
+
"opentelemetry-exporter-otlp-proto-grpc==1.27.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.urls]
|
|
33
|
+
Homepage = "https://github.com/pedrowill-dev/obskitpy"
|
|
34
|
+
Documentation = "https://github.com/pedrowill-dev/obskitpy/tree/main/docs"
|
|
35
|
+
Issues = "https://github.com/pedrowill-dev/obskitpy/issues"
|
|
36
|
+
|
|
37
|
+
[project.optional-dependencies]
|
|
38
|
+
requests = ["opentelemetry-instrumentation-requests==0.48b0", "setuptools==75.6.0"]
|
|
39
|
+
test = ["pytest"]
|
|
40
|
+
|
|
41
|
+
[project.scripts]
|
|
42
|
+
obskitpy = "obskitpy.cli:main"
|
|
43
|
+
|
|
44
|
+
[tool.setuptools.packages.find]
|
|
45
|
+
where = ["src"]
|
|
46
|
+
|
|
47
|
+
[tool.setuptools.package-data]
|
|
48
|
+
obskitpy = ["templates/*"]
|
obskitpy-0.1.0/setup.cfg
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
"""Uso:
|
|
2
|
+
|
|
3
|
+
import obskitpy
|
|
4
|
+
shutdown = obskitpy.setup("meu-servico") # logs, traces e métricas via OTLP
|
|
5
|
+
|
|
6
|
+
@obskitpy.traced() # span por chamada
|
|
7
|
+
def processar(item): ...
|
|
8
|
+
|
|
9
|
+
log.exception("falhou") # já sai com error.type/origin/chain
|
|
10
|
+
|
|
11
|
+
O endpoint vem de OTEL_EXPORTER_OTLP_ENDPOINT (padrão http://localhost:4317).
|
|
12
|
+
"""
|
|
13
|
+
import functools
|
|
14
|
+
import logging
|
|
15
|
+
import os
|
|
16
|
+
|
|
17
|
+
from opentelemetry import metrics, trace
|
|
18
|
+
from opentelemetry.trace import Status, StatusCode
|
|
19
|
+
|
|
20
|
+
from .errors import error_attributes, error_chain
|
|
21
|
+
|
|
22
|
+
__all__ = ["setup", "traced", "tracer", "meter", "error_chain", "error_attributes"]
|
|
23
|
+
|
|
24
|
+
_NOISY_LOGGERS = ("urllib3", "elastic_transport", "opentelemetry")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def tracer(name: str = "app"):
|
|
28
|
+
return trace.get_tracer(name)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def meter(name: str = "app"):
|
|
32
|
+
return metrics.get_meter(name)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def traced(name: str | None = None):
|
|
36
|
+
"""Decorator: abre um span por chamada e marca erro (com a exceção) se ela propagar."""
|
|
37
|
+
def wrap(fn):
|
|
38
|
+
span_name = name or f"{fn.__module__}.{fn.__qualname__}"
|
|
39
|
+
|
|
40
|
+
@functools.wraps(fn)
|
|
41
|
+
def inner(*args, **kwargs):
|
|
42
|
+
with trace.get_tracer(fn.__module__).start_as_current_span(span_name) as span:
|
|
43
|
+
try:
|
|
44
|
+
return fn(*args, **kwargs)
|
|
45
|
+
except Exception as exc:
|
|
46
|
+
span.record_exception(exc)
|
|
47
|
+
span.set_status(Status(StatusCode.ERROR, str(exc)))
|
|
48
|
+
raise
|
|
49
|
+
return inner
|
|
50
|
+
return wrap
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class _ErrorAttributes(logging.Filter):
|
|
54
|
+
"""Todo log com exc_info ganha error.type/origin/chain (sem o dev precisar passar `extra`)."""
|
|
55
|
+
|
|
56
|
+
def filter(self, record: logging.LogRecord) -> bool:
|
|
57
|
+
if record.exc_info and record.exc_info[1] is not None:
|
|
58
|
+
for key, value in error_attributes(record.exc_info[1]).items():
|
|
59
|
+
record.__dict__.setdefault(key, value)
|
|
60
|
+
return True
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def setup(service_name: str, *, environment: str | None = None, version: str = "0.0.0",
|
|
64
|
+
metrics_interval_ms: int = 10_000, instrument_requests: bool = True):
|
|
65
|
+
"""Configura traces, métricas e logs. Devolve a função que os descarrega ao encerrar."""
|
|
66
|
+
# O modo "otel" do Elasticsearch descarta histogramas cumulativos.
|
|
67
|
+
os.environ.setdefault("OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE", "delta")
|
|
68
|
+
os.environ.setdefault("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
|
|
69
|
+
|
|
70
|
+
from opentelemetry._logs import set_logger_provider
|
|
71
|
+
from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
|
|
72
|
+
from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter
|
|
73
|
+
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
|
|
74
|
+
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
|
|
75
|
+
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
|
|
76
|
+
from opentelemetry.sdk.metrics import MeterProvider
|
|
77
|
+
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
|
|
78
|
+
from opentelemetry.sdk.resources import Resource
|
|
79
|
+
from opentelemetry.sdk.trace import TracerProvider
|
|
80
|
+
from opentelemetry.sdk.trace.export import BatchSpanProcessor
|
|
81
|
+
|
|
82
|
+
resource = Resource.create({
|
|
83
|
+
"service.name": service_name,
|
|
84
|
+
"service.version": version,
|
|
85
|
+
"deployment.environment": environment or os.getenv("APP_ENV", "local"),
|
|
86
|
+
})
|
|
87
|
+
|
|
88
|
+
tracer_provider = TracerProvider(resource=resource)
|
|
89
|
+
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
|
|
90
|
+
trace.set_tracer_provider(tracer_provider)
|
|
91
|
+
|
|
92
|
+
meter_provider = MeterProvider(resource=resource, metric_readers=[
|
|
93
|
+
PeriodicExportingMetricReader(OTLPMetricExporter(), export_interval_millis=metrics_interval_ms)])
|
|
94
|
+
metrics.set_meter_provider(meter_provider)
|
|
95
|
+
|
|
96
|
+
logger_provider = LoggerProvider(resource=resource)
|
|
97
|
+
logger_provider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))
|
|
98
|
+
set_logger_provider(logger_provider)
|
|
99
|
+
|
|
100
|
+
root = logging.getLogger()
|
|
101
|
+
if not root.handlers:
|
|
102
|
+
logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
|
|
103
|
+
handler = LoggingHandler(level=logging.INFO, logger_provider=logger_provider)
|
|
104
|
+
handler.addFilter(_ErrorAttributes())
|
|
105
|
+
root.addHandler(handler)
|
|
106
|
+
for name in _NOISY_LOGGERS:
|
|
107
|
+
logging.getLogger(name).setLevel(logging.WARNING)
|
|
108
|
+
|
|
109
|
+
if instrument_requests:
|
|
110
|
+
try:
|
|
111
|
+
from opentelemetry.instrumentation.requests import RequestsInstrumentor
|
|
112
|
+
RequestsInstrumentor().instrument()
|
|
113
|
+
except ImportError:
|
|
114
|
+
pass # extra opcional: pip install "obskitpy[requests]"
|
|
115
|
+
|
|
116
|
+
def shutdown():
|
|
117
|
+
root.removeHandler(handler)
|
|
118
|
+
tracer_provider.shutdown()
|
|
119
|
+
meter_provider.shutdown()
|
|
120
|
+
logger_provider.shutdown()
|
|
121
|
+
|
|
122
|
+
return shutdown
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
"""obskitpy: observabilidade (OpenTelemetry + Elasticsearch + Kibana) em qualquer projeto Python."""
|
|
2
|
+
import argparse
|
|
3
|
+
import re
|
|
4
|
+
import shutil
|
|
5
|
+
import subprocess
|
|
6
|
+
import sys
|
|
7
|
+
import webbrowser
|
|
8
|
+
from importlib import resources
|
|
9
|
+
from pathlib import Path
|
|
10
|
+
|
|
11
|
+
from . import dashboard, kibana
|
|
12
|
+
|
|
13
|
+
DEFAULT_DIR = "observability"
|
|
14
|
+
DEFAULT_PORTS = {"ES_PORT": 9200, "KIBANA_PORT": 5601, "OTLP_GRPC_PORT": 4317, "OTLP_HTTP_PORT": 4318}
|
|
15
|
+
TEMPLATE_FILES = ("docker-compose.yml", "otel-collector-config.yaml")
|
|
16
|
+
SNIPPET = '''import obskitpy
|
|
17
|
+
|
|
18
|
+
shutdown = obskitpy.setup("{service}") # no início do programa
|
|
19
|
+
# ... seu código; use logging normalmente: log.exception("falhou") já vai com error.type/origin/chain
|
|
20
|
+
shutdown() # ao encerrar, descarrega os dados pendentes'''
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class CliError(Exception):
|
|
24
|
+
pass
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
# --- configuração (.env na pasta observability/) -------------------------------------------
|
|
28
|
+
|
|
29
|
+
def read_env(path: Path) -> dict[str, str]:
|
|
30
|
+
if not path.exists():
|
|
31
|
+
raise CliError(f"{path} não existe. Rode `obskitpy init` neste projeto primeiro.")
|
|
32
|
+
env = {}
|
|
33
|
+
for line in path.read_text().splitlines():
|
|
34
|
+
if "=" in line and not line.lstrip().startswith("#"):
|
|
35
|
+
key, _, value = line.partition("=")
|
|
36
|
+
env[key.strip()] = value.strip()
|
|
37
|
+
return env
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def kibana_url(env: dict[str, str]) -> str:
|
|
41
|
+
return f"http://localhost:{env['KIBANA_PORT']}"
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def dashboard_url(env: dict[str, str]) -> str:
|
|
45
|
+
return f"{kibana_url(env)}/app/dashboards#/view/{dashboard.dashboard_id(env['OBSKITPY_SERVICE'])}"
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
# --- comandos ------------------------------------------------------------------------------
|
|
49
|
+
|
|
50
|
+
def cmd_init(args) -> None:
|
|
51
|
+
obs = Path(args.dir)
|
|
52
|
+
service = args.service or re.sub(r"[^a-z0-9-]+", "-", Path.cwd().name.lower()).strip("-") or "app"
|
|
53
|
+
if not re.fullmatch(r"[a-z0-9][a-z0-9-]*", service):
|
|
54
|
+
raise CliError(f"nome de serviço inválido: {service!r} (use letras minúsculas, números e hífen)")
|
|
55
|
+
if (obs / ".env").exists() and not args.force:
|
|
56
|
+
raise CliError(f"{obs}/ já existe. Use --force para sobrescrever (o dashboard.ndjson é perdido).")
|
|
57
|
+
|
|
58
|
+
obs.mkdir(parents=True, exist_ok=True)
|
|
59
|
+
for name in TEMPLATE_FILES:
|
|
60
|
+
(obs / name).write_text(resources.files("obskitpy.templates").joinpath(name).read_text())
|
|
61
|
+
ports = {key: getattr(args, key.lower()) for key in DEFAULT_PORTS}
|
|
62
|
+
lines = ["# Gerado pelo obskitpy init; usado pelo docker compose e pela CLI.", f"OBSKITPY_SERVICE={service}"]
|
|
63
|
+
(obs / ".env").write_text("\n".join(lines + [f"{k}={v}" for k, v in ports.items()]) + "\n")
|
|
64
|
+
(obs / "dashboard.ndjson").write_text(dashboard.to_ndjson(dashboard.build(service)), encoding="utf-8")
|
|
65
|
+
|
|
66
|
+
print(f"Criado {obs}/ para o serviço '{service}':")
|
|
67
|
+
print(" docker-compose.yml otel-collector-config.yaml dashboard.ndjson .env")
|
|
68
|
+
print("\nPróximos passos:")
|
|
69
|
+
print(" 1. pip install obskitpy # (ou 'obskitpy[requests]' p/ spans HTTP automáticos)")
|
|
70
|
+
print(f" 2. obskitpy up --dir {obs}" if str(obs) != DEFAULT_DIR else " 2. obskitpy up")
|
|
71
|
+
print(" 3. No seu código:\n")
|
|
72
|
+
print(" " + SNIPPET.format(service=service).replace("\n", "\n "))
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def compose(obs: Path, env: dict[str, str], *args: str) -> None:
|
|
76
|
+
if shutil.which("docker") is None:
|
|
77
|
+
raise CliError("docker não encontrado no PATH.")
|
|
78
|
+
cmd = ["docker", "compose", "--project-directory", str(obs), "-f", str(obs / "docker-compose.yml"),
|
|
79
|
+
"-p", f"obskitpy-{env['OBSKITPY_SERVICE']}", *args]
|
|
80
|
+
if subprocess.run(cmd).returncode != 0:
|
|
81
|
+
raise CliError("docker compose falhou (o Docker/Colima está rodando?).")
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def apply_dashboard(obs: Path, env: dict[str, str]) -> None:
|
|
85
|
+
file = obs / "dashboard.ndjson"
|
|
86
|
+
if not file.exists():
|
|
87
|
+
raise CliError(f"{file} não existe.")
|
|
88
|
+
count = kibana.import_ndjson(kibana_url(env), file.read_text(encoding="utf-8"))
|
|
89
|
+
print(f"Dashboard aplicado ({count} objetos): {dashboard_url(env)}")
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def cmd_up(args) -> None:
|
|
93
|
+
obs = Path(args.dir)
|
|
94
|
+
env = read_env(obs / ".env")
|
|
95
|
+
compose(obs, env, "up", "-d", "--wait", "--wait-timeout", "300")
|
|
96
|
+
kibana.wait_ready(kibana_url(env))
|
|
97
|
+
apply_dashboard(obs, env)
|
|
98
|
+
print(f"\nOTLP gRPC: localhost:{env['OTLP_GRPC_PORT']} Elasticsearch: http://localhost:{env['ES_PORT']}")
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def cmd_down(args) -> None:
|
|
102
|
+
obs = Path(args.dir)
|
|
103
|
+
compose(obs, read_env(obs / ".env"), "down", *(["-v"] if args.volumes else []))
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
def cmd_status(args) -> None:
|
|
107
|
+
obs = Path(args.dir)
|
|
108
|
+
env = read_env(obs / ".env")
|
|
109
|
+
compose(obs, env, "ps")
|
|
110
|
+
print(f"\nDashboard: {dashboard_url(env)}")
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def cmd_open(args) -> None:
|
|
114
|
+
url = dashboard_url(read_env(Path(args.dir) / ".env"))
|
|
115
|
+
print(url)
|
|
116
|
+
webbrowser.open(url)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def cmd_dashboard_apply(args) -> None:
|
|
120
|
+
obs = Path(args.dir)
|
|
121
|
+
apply_dashboard(obs, read_env(obs / ".env"))
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def cmd_dashboard_export(args) -> None:
|
|
125
|
+
obs = Path(args.dir)
|
|
126
|
+
env = read_env(obs / ".env")
|
|
127
|
+
ndjson = kibana.export_dashboard(kibana_url(env), dashboard.dashboard_id(env["OBSKITPY_SERVICE"]))
|
|
128
|
+
if not ndjson.strip():
|
|
129
|
+
raise CliError("o Kibana não devolveu o dashboard (foi apagado? rode `obskitpy dashboard apply`).")
|
|
130
|
+
(obs / "dashboard.ndjson").write_text(ndjson, encoding="utf-8")
|
|
131
|
+
print(f"{obs}/dashboard.ndjson atualizado ({len(ndjson.splitlines())} objetos). Versione no git.")
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
# --- parser --------------------------------------------------------------------------------
|
|
135
|
+
|
|
136
|
+
def build_parser() -> argparse.ArgumentParser:
|
|
137
|
+
parser = argparse.ArgumentParser(prog="obskitpy", description=__doc__)
|
|
138
|
+
sub = parser.add_subparsers(dest="command", required=True)
|
|
139
|
+
|
|
140
|
+
def command(name, fn, help_, **kw):
|
|
141
|
+
p = sub.add_parser(name, help=help_, **kw)
|
|
142
|
+
p.add_argument("--dir", default=DEFAULT_DIR, help=f"pasta da stack (padrão: {DEFAULT_DIR})")
|
|
143
|
+
p.set_defaults(fn=fn)
|
|
144
|
+
return p
|
|
145
|
+
|
|
146
|
+
init = command("init", cmd_init, "cria a pasta observability/ com stack e dashboard base")
|
|
147
|
+
init.add_argument("--service", help="nome do serviço (padrão: nome da pasta atual)")
|
|
148
|
+
init.add_argument("--force", action="store_true", help="sobrescreve uma instalação existente")
|
|
149
|
+
for key, default in DEFAULT_PORTS.items():
|
|
150
|
+
init.add_argument(f"--{key.lower().replace('_', '-')}", dest=key.lower(), type=int, default=default,
|
|
151
|
+
help=f"porta local (padrão: {default})")
|
|
152
|
+
|
|
153
|
+
command("up", cmd_up, "sobe a stack, espera ficar saudável e aplica o dashboard")
|
|
154
|
+
down = command("down", cmd_down, "derruba a stack")
|
|
155
|
+
down.add_argument("-v", "--volumes", action="store_true", help="apaga também os dados")
|
|
156
|
+
command("status", cmd_status, "mostra os containers e o link do dashboard")
|
|
157
|
+
command("open", cmd_open, "abre o dashboard no navegador")
|
|
158
|
+
|
|
159
|
+
dash = sub.add_parser("dashboard", help="sincroniza o dashboard com o Kibana")
|
|
160
|
+
dsub = dash.add_subparsers(dest="action", required=True)
|
|
161
|
+
for name, fn, help_ in (("apply", cmd_dashboard_apply, "importa observability/dashboard.ndjson no Kibana"),
|
|
162
|
+
("export", cmd_dashboard_export, "grava o dashboard do Kibana (com suas edições) no arquivo")):
|
|
163
|
+
p = dsub.add_parser(name, help=help_)
|
|
164
|
+
p.add_argument("--dir", default=DEFAULT_DIR)
|
|
165
|
+
p.set_defaults(fn=fn)
|
|
166
|
+
return parser
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
def main(argv: list[str] | None = None) -> None:
|
|
170
|
+
args = build_parser().parse_args(argv)
|
|
171
|
+
try:
|
|
172
|
+
args.fn(args)
|
|
173
|
+
except (CliError, kibana.KibanaError) as exc:
|
|
174
|
+
sys.exit(f"erro: {exc}")
|
|
175
|
+
|
|
176
|
+
|
|
177
|
+
if __name__ == "__main__":
|
|
178
|
+
main()
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
"""Dashboard base (genérico, por serviço) como saved objects do Kibana 8.x.
|
|
2
|
+
|
|
3
|
+
O dev evolui o dashboard no próprio Kibana e grava com `obskitpy dashboard export`;
|
|
4
|
+
este módulo só gera o ponto de partida do `obskitpy init`.
|
|
5
|
+
"""
|
|
6
|
+
import json
|
|
7
|
+
|
|
8
|
+
KIBANA_VERSION = "8.17.0"
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def search_source(query: str) -> str:
|
|
12
|
+
return json.dumps(
|
|
13
|
+
{
|
|
14
|
+
"query": {"query": query, "language": "kuery"},
|
|
15
|
+
"filter": [],
|
|
16
|
+
"indexRefName": "kibanaSavedObjectMeta.searchSourceJSON.index",
|
|
17
|
+
}
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def agg(id_, type_, schema, label=None, **params):
|
|
22
|
+
item = {"id": str(id_), "enabled": True, "type": type_, "params": params, "schema": schema}
|
|
23
|
+
if label:
|
|
24
|
+
item["params"]["customLabel"] = label
|
|
25
|
+
return item
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def terms(id_, field, label, order_by="1", size=10, schema="segment"):
|
|
29
|
+
return agg(id_, "terms", schema, label, field=field, orderBy=order_by, order="desc",
|
|
30
|
+
size=size, otherBucket=False, missingBucket=False)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def date_histogram(id_, schema="segment", field="@timestamp", interval="auto"):
|
|
34
|
+
return agg(id_, "date_histogram", schema, field=field, useNormalizedEsInterval=True,
|
|
35
|
+
scaleMetricValues=False, interval=interval, drop_partials=False, min_doc_count=1,
|
|
36
|
+
extended_bounds={})
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def chart_params(kind, value_title):
|
|
40
|
+
return {
|
|
41
|
+
"type": kind,
|
|
42
|
+
"grid": {"categoryLines": False},
|
|
43
|
+
"categoryAxes": [{"id": "CategoryAxis-1", "type": "category", "position": "bottom", "show": True,
|
|
44
|
+
"style": {}, "scale": {"type": "linear"},
|
|
45
|
+
"labels": {"show": True, "filter": True, "truncate": 100}, "title": {}}],
|
|
46
|
+
"valueAxes": [{"id": "ValueAxis-1", "name": "LeftAxis-1", "type": "value", "position": "left",
|
|
47
|
+
"show": True, "style": {}, "scale": {"type": "linear", "mode": "normal"},
|
|
48
|
+
"labels": {"show": True, "rotate": 0, "filter": False, "truncate": 100},
|
|
49
|
+
"title": {"text": value_title}}],
|
|
50
|
+
"seriesParams": [{"show": True, "type": kind, "mode": "normal",
|
|
51
|
+
"data": {"label": value_title, "id": "1"}, "valueAxis": "ValueAxis-1",
|
|
52
|
+
"drawLinesBetweenPoints": True, "lineWidth": 2, "showCircles": True}],
|
|
53
|
+
"addTooltip": True, "addLegend": True, "legendPosition": "right", "times": [],
|
|
54
|
+
"addTimeMarker": False, "labels": {},
|
|
55
|
+
"thresholdLine": {"show": False, "value": 10, "width": 1, "style": "full", "color": "#E7664C"},
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def metric_vis(title, aggs):
|
|
60
|
+
return {"title": title, "type": "metric", "aggs": aggs, "params": {
|
|
61
|
+
"addTooltip": True, "addLegend": False, "type": "metric",
|
|
62
|
+
"metric": {"percentageMode": False, "useRanges": False, "colorSchema": "Green to Red",
|
|
63
|
+
"metricColorMode": "None", "colorsRange": [{"from": 0, "to": 10000}],
|
|
64
|
+
"labels": {"show": True}, "invertColors": False,
|
|
65
|
+
"style": {"bgFill": "#000", "bgColor": False, "labelColor": False,
|
|
66
|
+
"subText": "", "fontSize": 48}}}}
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def chart_vis(title, kind, aggs, value_title):
|
|
70
|
+
return {"title": title, "type": kind, "aggs": aggs, "params": chart_params(kind, value_title)}
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def table_vis(title, aggs):
|
|
74
|
+
return {"title": title, "type": "table", "aggs": aggs, "params": {
|
|
75
|
+
"perPage": 10, "showPartialRows": False, "showMetricsAtAllLevels": False,
|
|
76
|
+
"showTotal": False, "totalFunc": "sum", "percentageCol": ""}}
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def ref(idx_id):
|
|
80
|
+
return [{"name": "kibanaSavedObjectMeta.searchSourceJSON.index", "type": "index-pattern", "id": idx_id}]
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def build(service: str) -> list[dict]:
|
|
84
|
+
"""Objetos do dashboard `<service>-observability`, filtrados por service.name."""
|
|
85
|
+
def sid(kind):
|
|
86
|
+
return f"{service}-{kind}"
|
|
87
|
+
|
|
88
|
+
scope = f'resource.attributes.service.name : "{service}"'
|
|
89
|
+
|
|
90
|
+
def q(extra=""):
|
|
91
|
+
return f"{scope} and {extra}" if extra else scope
|
|
92
|
+
|
|
93
|
+
errors = q('severity_text : "ERROR"')
|
|
94
|
+
data_views = {
|
|
95
|
+
sid("logs"): ("Logs", "logs-generic.otel-*"),
|
|
96
|
+
sid("traces"): ("Traces", "traces-generic.otel-*"),
|
|
97
|
+
}
|
|
98
|
+
# (id, data view, query, definição, x, y, w, h)
|
|
99
|
+
visualizations = [
|
|
100
|
+
(sid("v-logs"), "logs", q(), metric_vis("Logs", [agg(1, "count", "metric", "Logs")]), 0, 0, 12, 8),
|
|
101
|
+
(sid("v-errors"), "logs", errors, metric_vis("Erros", [agg(1, "count", "metric", "Erros")]), 12, 0, 12, 8),
|
|
102
|
+
(sid("v-traces"), "traces", q("name : * and not parent_span_id : *"),
|
|
103
|
+
metric_vis("Execuções (traces)", [agg(1, "count", "metric", "Execuções")]), 24, 0, 12, 8),
|
|
104
|
+
(sid("v-failed"), "traces", q('status.code : "Error" and name : * and not parent_span_id : *'),
|
|
105
|
+
metric_vis("Execuções com erro", [agg(1, "count", "metric", "Com erro")]), 36, 0, 12, 8),
|
|
106
|
+
(sid("v-logs-time"), "logs", q(),
|
|
107
|
+
chart_vis("Logs por severidade", "histogram",
|
|
108
|
+
[agg(1, "count", "metric", "Logs"), date_histogram(2),
|
|
109
|
+
terms(3, "severity_text", "Severidade", schema="group")], "Logs"), 0, 8, 24, 14),
|
|
110
|
+
(sid("v-spans-time"), "traces", q(),
|
|
111
|
+
chart_vis("Spans por operação", "line",
|
|
112
|
+
[agg(1, "count", "metric", "Spans"), date_histogram(2),
|
|
113
|
+
terms(3, "name", "Span", size=5, schema="group")], "Spans"), 24, 8, 24, 14),
|
|
114
|
+
(sid("v-spans"), "traces", q(),
|
|
115
|
+
table_vis("Duração dos spans (ns)", [
|
|
116
|
+
agg(1, "avg", "metric", "Média (ns)", field="duration"),
|
|
117
|
+
agg(3, "max", "metric", "Máxima (ns)", field="duration"),
|
|
118
|
+
agg(4, "count", "metric", "Qtd"),
|
|
119
|
+
terms(2, "name", "Span", size=20, schema="bucket")]), 0, 22, 24, 14),
|
|
120
|
+
(sid("v-error-origin"), "logs", errors,
|
|
121
|
+
table_vis("Erros por tipo e origem", [
|
|
122
|
+
agg(1, "count", "metric", "Qtd"),
|
|
123
|
+
terms(2, "attributes.error.type", "Tipo", schema="bucket"),
|
|
124
|
+
terms(3, "attributes.error.origin", "Origem (arquivo:função:linha)", schema="bucket")]),
|
|
125
|
+
24, 22, 24, 14),
|
|
126
|
+
]
|
|
127
|
+
|
|
128
|
+
objects = [{"type": "index-pattern", "id": id_, "references": [],
|
|
129
|
+
"attributes": {"title": pattern, "name": f"{service} - {name}", "timeFieldName": "@timestamp"}}
|
|
130
|
+
for id_, (name, pattern) in data_views.items()]
|
|
131
|
+
|
|
132
|
+
panels, dash_refs = [], []
|
|
133
|
+
for n, (id_, view, query, vis, x, y, w, h) in enumerate(visualizations):
|
|
134
|
+
objects.append({
|
|
135
|
+
"type": "visualization", "id": id_, "references": ref(sid(view)),
|
|
136
|
+
"attributes": {"title": vis["title"], "visState": json.dumps(vis), "uiStateJSON": "{}",
|
|
137
|
+
"description": "", "version": 1,
|
|
138
|
+
"kibanaSavedObjectMeta": {"searchSourceJSON": search_source(query)}}})
|
|
139
|
+
panels.append({"version": KIBANA_VERSION, "type": "visualization", "panelIndex": str(n),
|
|
140
|
+
"gridData": {"x": x, "y": y, "w": w, "h": h, "i": str(n)},
|
|
141
|
+
"embeddableConfig": {}, "panelRefName": f"panel_{n}"})
|
|
142
|
+
dash_refs.append({"name": f"panel_{n}", "type": "visualization", "id": id_})
|
|
143
|
+
|
|
144
|
+
search_id = sid("s-errors")
|
|
145
|
+
objects.append({
|
|
146
|
+
"type": "search", "id": search_id, "references": ref(sid("logs")),
|
|
147
|
+
"attributes": {"title": "Erros (logs)", "description": "", "version": 1, "hits": 0,
|
|
148
|
+
"columns": ["body.text", "attributes.error.type", "attributes.error.origin", "trace_id"],
|
|
149
|
+
"sort": [["@timestamp", "desc"]],
|
|
150
|
+
"kibanaSavedObjectMeta": {"searchSourceJSON": search_source(errors)}}})
|
|
151
|
+
n = len(visualizations)
|
|
152
|
+
panels.append({"version": KIBANA_VERSION, "type": "search", "panelIndex": str(n),
|
|
153
|
+
"gridData": {"x": 0, "y": 36, "w": 48, "h": 14, "i": str(n)},
|
|
154
|
+
"embeddableConfig": {}, "panelRefName": f"panel_{n}"})
|
|
155
|
+
dash_refs.append({"name": f"panel_{n}", "type": "search", "id": search_id})
|
|
156
|
+
|
|
157
|
+
objects.append({
|
|
158
|
+
"type": "dashboard", "id": dashboard_id(service), "references": dash_refs,
|
|
159
|
+
"attributes": {
|
|
160
|
+
"title": f"{service} - Observabilidade",
|
|
161
|
+
"description": "Logs, traces e erros do serviço. Evolua este dashboard no Kibana e rode `obskitpy dashboard export`.",
|
|
162
|
+
"hits": 0, "version": 1, "panelsJSON": json.dumps(panels),
|
|
163
|
+
"optionsJSON": json.dumps({"useMargins": True, "syncColors": False, "syncCursor": True,
|
|
164
|
+
"syncTooltips": False, "hidePanelTitles": False}),
|
|
165
|
+
"timeRestore": True, "timeFrom": "now-24h", "timeTo": "now",
|
|
166
|
+
"refreshInterval": {"pause": False, "value": 30000},
|
|
167
|
+
"kibanaSavedObjectMeta": {"searchSourceJSON": json.dumps(
|
|
168
|
+
{"query": {"query": "", "language": "kuery"}, "filter": []})}}})
|
|
169
|
+
return objects
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def dashboard_id(service: str) -> str:
|
|
173
|
+
return f"{service}-observability"
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def to_ndjson(objects: list[dict]) -> str:
|
|
177
|
+
return "\n".join(json.dumps(o, ensure_ascii=False) for o in objects) + "\n"
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""Diagnóstico estruturado de exceções: cadeia de chamadas e ponto de origem."""
|
|
2
|
+
import json
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def error_chain(error: BaseException) -> list[dict]:
|
|
7
|
+
"""Um item por frame do traceback, do mais externo ao ponto onde o erro nasceu."""
|
|
8
|
+
chain, tb = [], error.__traceback__
|
|
9
|
+
while tb is not None:
|
|
10
|
+
code = tb.tb_frame.f_code
|
|
11
|
+
chain.append({"funcao": code.co_name, "arquivo": Path(code.co_filename).name, "linha": tb.tb_lineno})
|
|
12
|
+
tb = tb.tb_next
|
|
13
|
+
return chain
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def error_attributes(error: BaseException) -> dict:
|
|
17
|
+
"""Atributos `error.*` anexados aos logs de erro (usados pelos painéis do dashboard)."""
|
|
18
|
+
chain = error_chain(error)
|
|
19
|
+
attrs = {"error.type": type(error).__name__}
|
|
20
|
+
if chain:
|
|
21
|
+
last = chain[-1]
|
|
22
|
+
attrs["error.origin"] = f"{last['arquivo']}:{last['funcao']}:{last['linha']}"
|
|
23
|
+
attrs["error.chain"] = json.dumps(chain, ensure_ascii=False)
|
|
24
|
+
return attrs
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""Cliente mínimo da API de saved objects do Kibana (stdlib)."""
|
|
2
|
+
import json
|
|
3
|
+
import time
|
|
4
|
+
import urllib.error
|
|
5
|
+
import urllib.request
|
|
6
|
+
import uuid
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class KibanaError(RuntimeError):
|
|
10
|
+
pass
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def _request(url: str, data: bytes | None = None, headers: dict | None = None, timeout: int = 60) -> bytes:
|
|
14
|
+
req = urllib.request.Request(url, data=data, headers={"kbn-xsrf": "obskitpy", **(headers or {})})
|
|
15
|
+
try:
|
|
16
|
+
with urllib.request.urlopen(req, timeout=timeout) as resp:
|
|
17
|
+
return resp.read()
|
|
18
|
+
except urllib.error.HTTPError as exc:
|
|
19
|
+
raise KibanaError(f"{url}: HTTP {exc.code} {exc.read().decode(errors='replace')[:300]}") from exc
|
|
20
|
+
except urllib.error.URLError as exc:
|
|
21
|
+
raise KibanaError(f"{url}: {exc.reason}") from exc
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def wait_ready(base: str, timeout: int = 300) -> None:
|
|
25
|
+
deadline = time.time() + timeout
|
|
26
|
+
while True:
|
|
27
|
+
try:
|
|
28
|
+
if json.loads(_request(f"{base}/api/status", timeout=5))["status"]["overall"]["level"] == "available":
|
|
29
|
+
return
|
|
30
|
+
except (KibanaError, ValueError, KeyError):
|
|
31
|
+
pass
|
|
32
|
+
if time.time() > deadline:
|
|
33
|
+
raise KibanaError(f"Kibana não ficou disponível em {base} (timeout {timeout}s)")
|
|
34
|
+
time.sleep(3)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def import_ndjson(base: str, ndjson: str) -> int:
|
|
38
|
+
boundary = uuid.uuid4().hex
|
|
39
|
+
body = (f"--{boundary}\r\nContent-Disposition: form-data; name=\"file\"; filename=\"dashboard.ndjson\"\r\n"
|
|
40
|
+
f"Content-Type: application/ndjson\r\n\r\n{ndjson}\r\n--{boundary}--\r\n").encode()
|
|
41
|
+
out = json.loads(_request(f"{base}/api/saved_objects/_import?overwrite=true", body,
|
|
42
|
+
{"Content-Type": f"multipart/form-data; boundary={boundary}"}))
|
|
43
|
+
if not out.get("success"):
|
|
44
|
+
raise KibanaError(f"importação falhou: {json.dumps(out.get('errors'), ensure_ascii=False)[:500]}")
|
|
45
|
+
return out.get("successCount", 0)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def export_dashboard(base: str, dashboard_id: str) -> str:
|
|
49
|
+
body = json.dumps({"objects": [{"type": "dashboard", "id": dashboard_id}],
|
|
50
|
+
"includeReferencesDeep": True, "excludeExportDetails": True}).encode()
|
|
51
|
+
return _request(f"{base}/api/saved_objects/_export", body, {"Content-Type": "application/json"}).decode()
|
|
File without changes
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Gerado pelo obskitpy. Ambiente local: segurança do Elasticsearch desligada, portas só em 127.0.0.1.
|
|
2
|
+
# Portas e serviço vêm do .env desta pasta.
|
|
3
|
+
services:
|
|
4
|
+
elasticsearch:
|
|
5
|
+
image: docker.elastic.co/elasticsearch/elasticsearch:8.17.0
|
|
6
|
+
environment:
|
|
7
|
+
discovery.type: single-node
|
|
8
|
+
xpack.security.enabled: "false"
|
|
9
|
+
ES_JAVA_OPTS: -Xms1g -Xmx1g
|
|
10
|
+
ports: ["127.0.0.1:${ES_PORT:-9200}:9200"]
|
|
11
|
+
volumes: [esdata:/usr/share/elasticsearch/data]
|
|
12
|
+
healthcheck:
|
|
13
|
+
test: ["CMD-SHELL", "curl -fs http://localhost:9200/_cluster/health | grep -qE '\"status\":\"(green|yellow)\"'"]
|
|
14
|
+
interval: 10s
|
|
15
|
+
timeout: 5s
|
|
16
|
+
retries: 30
|
|
17
|
+
|
|
18
|
+
kibana:
|
|
19
|
+
image: docker.elastic.co/kibana/kibana:8.17.0
|
|
20
|
+
environment:
|
|
21
|
+
ELASTICSEARCH_HOSTS: http://elasticsearch:9200
|
|
22
|
+
ports: ["127.0.0.1:${KIBANA_PORT:-5601}:5601"]
|
|
23
|
+
depends_on:
|
|
24
|
+
elasticsearch: {condition: service_healthy}
|
|
25
|
+
healthcheck:
|
|
26
|
+
test: ["CMD-SHELL", "curl -fs http://localhost:5601/api/status | grep -q '\"level\":\"available\"'"]
|
|
27
|
+
interval: 10s
|
|
28
|
+
timeout: 5s
|
|
29
|
+
retries: 30
|
|
30
|
+
|
|
31
|
+
otel-collector:
|
|
32
|
+
image: otel/opentelemetry-collector-contrib:0.116.1
|
|
33
|
+
command: ["--config=/etc/otelcol/config.yaml"]
|
|
34
|
+
volumes: ["./otel-collector-config.yaml:/etc/otelcol/config.yaml:ro"]
|
|
35
|
+
ports: ["127.0.0.1:${OTLP_GRPC_PORT:-4317}:4317", "127.0.0.1:${OTLP_HTTP_PORT:-4318}:4318"]
|
|
36
|
+
depends_on:
|
|
37
|
+
elasticsearch: {condition: service_healthy}
|
|
38
|
+
|
|
39
|
+
volumes:
|
|
40
|
+
esdata:
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Gerado pelo obskitpy. Modo "otel": data streams logs-/traces-/metrics-generic.otel-default (ES 8.16+).
|
|
2
|
+
receivers:
|
|
3
|
+
otlp:
|
|
4
|
+
protocols:
|
|
5
|
+
grpc: {endpoint: 0.0.0.0:4317}
|
|
6
|
+
http: {endpoint: 0.0.0.0:4318}
|
|
7
|
+
|
|
8
|
+
processors:
|
|
9
|
+
batch: {}
|
|
10
|
+
|
|
11
|
+
exporters:
|
|
12
|
+
elasticsearch:
|
|
13
|
+
endpoints: [http://elasticsearch:9200]
|
|
14
|
+
logs_index: logs-generic.otel-default
|
|
15
|
+
traces_index: traces-generic.otel-default
|
|
16
|
+
metrics_index: metrics-generic.otel-default
|
|
17
|
+
mapping:
|
|
18
|
+
mode: otel
|
|
19
|
+
|
|
20
|
+
service:
|
|
21
|
+
pipelines:
|
|
22
|
+
logs: {receivers: [otlp], processors: [batch], exporters: [elasticsearch]}
|
|
23
|
+
traces: {receivers: [otlp], processors: [batch], exporters: [elasticsearch]}
|
|
24
|
+
metrics: {receivers: [otlp], processors: [batch], exporters: [elasticsearch]}
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: obskitpy
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Observabilidade (OpenTelemetry + Elasticsearch + Kibana) para qualquer projeto Python, via CLI.
|
|
5
|
+
Author: Pedro França
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/pedrowill-dev/obskitpy
|
|
8
|
+
Project-URL: Documentation, https://github.com/pedrowill-dev/obskitpy/tree/main/docs
|
|
9
|
+
Project-URL: Issues, https://github.com/pedrowill-dev/obskitpy/issues
|
|
10
|
+
Keywords: observability,opentelemetry,elasticsearch,kibana,rpa,logging,tracing
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: System :: Monitoring
|
|
19
|
+
Classifier: Topic :: System :: Logging
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: opentelemetry-api==1.27.0
|
|
24
|
+
Requires-Dist: opentelemetry-sdk==1.27.0
|
|
25
|
+
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc==1.27.0
|
|
26
|
+
Provides-Extra: requests
|
|
27
|
+
Requires-Dist: opentelemetry-instrumentation-requests==0.48b0; extra == "requests"
|
|
28
|
+
Requires-Dist: setuptools==75.6.0; extra == "requests"
|
|
29
|
+
Provides-Extra: test
|
|
30
|
+
Requires-Dist: pytest; extra == "test"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
<p align="center"><img src="https://raw.githubusercontent.com/pedrowill-dev/obskitpy/main/docs/images/logo.png" alt="obskitpy" width="380"></p>
|
|
34
|
+
|
|
35
|
+
# obskitpy
|
|
36
|
+
|
|
37
|
+
Observabilidade (OpenTelemetry → Elasticsearch → Kibana) em qualquer projeto Python, via CLI.
|
|
38
|
+
|
|
39
|
+
> Documentação completa na raiz do repositório: [`docs/`](../docs/inicio-rapido.md). Este arquivo é um resumo.
|
|
40
|
+
|
|
41
|
+
## Começar (2 comandos)
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
uv add "obskitpy[requests]" # ou pip install; o extra 'requests' adiciona spans HTTP automáticos
|
|
45
|
+
cd meu-projeto
|
|
46
|
+
obskitpy init # cria observability/ (stack + dashboard base); --service NOME opcional
|
|
47
|
+
obskitpy up # sobe ES + Kibana + Collector e cria o dashboard
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
No código:
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
import logging, obskitpy
|
|
54
|
+
|
|
55
|
+
log = logging.getLogger(__name__)
|
|
56
|
+
shutdown = obskitpy.setup("meu-servico") # logs + traces + métricas via OTLP (localhost:4317)
|
|
57
|
+
|
|
58
|
+
@obskitpy.traced() # um span por chamada, marca erro se a exceção propagar
|
|
59
|
+
def processar(item): ...
|
|
60
|
+
|
|
61
|
+
try:
|
|
62
|
+
processar(x)
|
|
63
|
+
except Exception:
|
|
64
|
+
log.exception("falhou") # já sai com error.type, error.origin e error.chain
|
|
65
|
+
|
|
66
|
+
shutdown() # descarrega os dados pendentes
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Métricas próprias: `obskitpy.meter().create_counter("pedidos.processados")` (API do OpenTelemetry).
|
|
70
|
+
|
|
71
|
+
## Comandos
|
|
72
|
+
|
|
73
|
+
| Comando | O que faz |
|
|
74
|
+
|---|---|
|
|
75
|
+
| `obskitpy init [--service N] [--kibana-port P ...]` | cria `observability/` (compose, collector, `dashboard.ndjson`, `.env`) |
|
|
76
|
+
| `obskitpy up` | sobe a stack, espera ficar saudável e **aplica o dashboard** |
|
|
77
|
+
| `obskitpy down [-v]` | derruba (`-v` apaga os dados) |
|
|
78
|
+
| `obskitpy status` / `obskitpy open` | containers + link / abre o dashboard |
|
|
79
|
+
| `obskitpy dashboard export` | grava no arquivo o dashboard **como está no Kibana** |
|
|
80
|
+
| `obskitpy dashboard apply` | importa `observability/dashboard.ndjson` no Kibana |
|
|
81
|
+
|
|
82
|
+
Todos aceitam `--dir` (padrão `observability`).
|
|
83
|
+
|
|
84
|
+
## Evoluindo o dashboard
|
|
85
|
+
|
|
86
|
+
1. `obskitpy up` já cria o dashboard `<servico>-observability` com os painéis básicos: logs, erros, execuções (traces), duração de spans, erros por tipo/origem e lista de erros com `trace_id`.
|
|
87
|
+
2. Edite no Kibana (adicione painéis, métricas do seu domínio, filtros).
|
|
88
|
+
3. `obskitpy dashboard export` e versione `observability/dashboard.ndjson` no git.
|
|
89
|
+
4. Em outra máquina/CI: `obskitpy up` (ou `obskitpy dashboard apply`) recria tudo.
|
|
90
|
+
|
|
91
|
+
Os painéis filtram por `resource.attributes.service.name`, então vários serviços podem compartilhar uma stack (use o mesmo `--dir`/portas) ou ter uma cada (use portas diferentes no `init`).
|
|
92
|
+
|
|
93
|
+
## Observações
|
|
94
|
+
|
|
95
|
+
- Ambiente local: segurança do Elasticsearch desligada, portas só em `127.0.0.1`.
|
|
96
|
+
- Os dados demoram alguns segundos para ficar pesquisáveis após o primeiro envio.
|
|
97
|
+
- Colima/Docker: o `docker compose` precisa enxergar a pasta do projeto (no Colima, só `$HOME` é montado por padrão).
|
|
98
|
+
- Requer Docker com o plugin Compose v2.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
src/obskitpy/__init__.py
|
|
5
|
+
src/obskitpy/cli.py
|
|
6
|
+
src/obskitpy/dashboard.py
|
|
7
|
+
src/obskitpy/errors.py
|
|
8
|
+
src/obskitpy/kibana.py
|
|
9
|
+
src/obskitpy.egg-info/PKG-INFO
|
|
10
|
+
src/obskitpy.egg-info/SOURCES.txt
|
|
11
|
+
src/obskitpy.egg-info/dependency_links.txt
|
|
12
|
+
src/obskitpy.egg-info/entry_points.txt
|
|
13
|
+
src/obskitpy.egg-info/requires.txt
|
|
14
|
+
src/obskitpy.egg-info/top_level.txt
|
|
15
|
+
src/obskitpy/templates/__init__.py
|
|
16
|
+
src/obskitpy/templates/docker-compose.yml
|
|
17
|
+
src/obskitpy/templates/otel-collector-config.yaml
|
|
18
|
+
tests/test_obskitpy.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
obskitpy
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import json
|
|
2
|
+
|
|
3
|
+
import pytest
|
|
4
|
+
|
|
5
|
+
from obskitpy import dashboard, errors
|
|
6
|
+
from obskitpy.cli import main
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def test_dashboard_is_scoped_and_consistent():
|
|
10
|
+
objects = dashboard.build("meu-app")
|
|
11
|
+
ids = {(o["type"], o["id"]) for o in objects}
|
|
12
|
+
dash = next(o for o in objects if o["type"] == "dashboard")
|
|
13
|
+
assert dash["id"] == "meu-app-observability"
|
|
14
|
+
for r in dash["references"]:
|
|
15
|
+
assert (r["type"], r["id"]) in ids
|
|
16
|
+
for o in objects:
|
|
17
|
+
for r in o["references"]:
|
|
18
|
+
assert (r["type"], r["id"]) in ids
|
|
19
|
+
for o in objects:
|
|
20
|
+
if o["type"] in ("visualization", "search"):
|
|
21
|
+
query = json.loads(o["attributes"]["kibanaSavedObjectMeta"]["searchSourceJSON"])["query"]["query"]
|
|
22
|
+
assert 'resource.attributes.service.name : "meu-app"' in query
|
|
23
|
+
assert len(dashboard.to_ndjson(objects).splitlines()) == len(objects)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def test_init_creates_files_and_refuses_overwrite(tmp_path, capsys):
|
|
27
|
+
obs = tmp_path / "observability"
|
|
28
|
+
main(["init", "--dir", str(obs), "--service", "pedidos", "--kibana-port", "5700"])
|
|
29
|
+
assert {p.name for p in obs.iterdir()} == {
|
|
30
|
+
".env", "docker-compose.yml", "otel-collector-config.yaml", "dashboard.ndjson"}
|
|
31
|
+
env = (obs / ".env").read_text()
|
|
32
|
+
assert "OBSKITPY_SERVICE=pedidos" in env and "KIBANA_PORT=5700" in env
|
|
33
|
+
for line in (obs / "dashboard.ndjson").read_text().splitlines():
|
|
34
|
+
json.loads(line)
|
|
35
|
+
with pytest.raises(SystemExit):
|
|
36
|
+
main(["init", "--dir", str(obs), "--service", "pedidos"])
|
|
37
|
+
assert "obskitpy.setup(\"pedidos\")" in capsys.readouterr().out
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def test_init_rejects_bad_service(tmp_path):
|
|
41
|
+
with pytest.raises(SystemExit):
|
|
42
|
+
main(["init", "--dir", str(tmp_path / "o"), "--service", "Nome Ruim"])
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def test_commands_need_init(tmp_path):
|
|
46
|
+
with pytest.raises(SystemExit):
|
|
47
|
+
main(["up", "--dir", str(tmp_path / "nada")])
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def test_error_attributes():
|
|
51
|
+
def inner():
|
|
52
|
+
raise ValueError("x")
|
|
53
|
+
|
|
54
|
+
try:
|
|
55
|
+
inner()
|
|
56
|
+
except ValueError as exc:
|
|
57
|
+
attrs = errors.error_attributes(exc)
|
|
58
|
+
assert attrs["error.type"] == "ValueError"
|
|
59
|
+
assert attrs["error.origin"].endswith(":inner:" + attrs["error.origin"].split(":")[-1])
|
|
60
|
+
assert json.loads(attrs["error.chain"])[-1]["funcao"] == "inner"
|