obskitpy 0.1.0__py3-none-any.whl

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/__init__.py 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
obskitpy/cli.py ADDED
@@ -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()
obskitpy/dashboard.py ADDED
@@ -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"
obskitpy/errors.py ADDED
@@ -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
obskitpy/kibana.py ADDED
@@ -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,14 @@
1
+ obskitpy/__init__.py,sha256=4QNVGh1ogFRLFC7S-tEXCCYDZkid5oUTRXPJ248dGqQ,4861
2
+ obskitpy/cli.py,sha256=Dlc7PCR1S6xVryUJcCZM1nK_7ufhfgW5WQVCqMTUj2Y,7555
3
+ obskitpy/dashboard.py,sha256=ypqmaYWISD6NtPtfXCzjmBhTYQlcskaKDLRm47zJ0h4,9055
4
+ obskitpy/errors.py,sha256=eGCf7r2znbdcf0uhCMn5D1lUY7Y_DGaP2YN7HKQXjHs,953
5
+ obskitpy/kibana.py,sha256=NLlUid8_pBe9FwQcwZQdgyEc8WRvRsovwQhYDgNJEMY,2233
6
+ obskitpy/templates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
7
+ obskitpy/templates/docker-compose.yml,sha256=wGmT16Vvu0Ao7j208KZDQbQccbwhpK7tlbz4ce_buDo,1465
8
+ obskitpy/templates/otel-collector-config.yaml,sha256=Cxp-IMbHZQyGRecv64ftO_bbwthLHJjsS-bOa7N6btU,745
9
+ obskitpy-0.1.0.dist-info/licenses/LICENSE,sha256=8nRlKZpUfJyvTVog_V-6AcsOtdjF-GXzcIXfH3S6-ak,1070
10
+ obskitpy-0.1.0.dist-info/METADATA,sha256=3IhhgAjr2AEoXwulGrcS7bSZioq82Jogdtm8Y-hrg9k,4378
11
+ obskitpy-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
12
+ obskitpy-0.1.0.dist-info/entry_points.txt,sha256=Wy9Ob61pKkyaW9HOaa8O3oAAUH6WJeDg6II_4dZ3PYA,47
13
+ obskitpy-0.1.0.dist-info/top_level.txt,sha256=hsAACw_aqPKpQICYHyoErauxHItRUbS4ENYDHU0Wkqg,9
14
+ obskitpy-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ obskitpy = obskitpy.cli:main
@@ -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.
@@ -0,0 +1 @@
1
+ obskitpy