Seu pipeline de CAPTCHA está lento e você não sabe se o gargalo é o envio da tarefa, o polling ou a rede? A resposta certa quase nunca é "aumente o timeout" — é medir. Com OpenTelemetry (OTel) você instrumenta o pipeline uma única vez e exporta os spans para Jaeger, Zipkin, Datadog ou qualquer back-end compatível com OTel, sem prender o projeto a um fornecedor específico. O resultado é visibilidade span a span: quanto tempo o in.php levou para responder, quantos polls o res.php precisou até devolver a solução, e onde exatamente o tempo total foi parar.
Este guia traz:
- a estrutura de spans de um pipeline de CAPTCHA, do scrape ao token aplicado;
- instrumentação completa em Python e em Node.js;
- a configuração do coletor OTel para exportar a um ou mais back-ends;
- como ler os spans na prática, com um cenário comum para quem opera fora dos EUA;
- os erros mais frequentes ao instrumentar e como corrigi-los.
Como fica o rastreamento de um pipeline de CAPTCHA
[Scrape Page]
└── [Solve CAPTCHA] ← Parent span
├── [Submit Task] ← HTTP POST to in.php
├── [Poll Result] ← Repeated GET to res.php
│ ├── [Poll Attempt 1] ← CAPCHA_NOT_READY
│ ├── [Poll Attempt 2] ← CAPCHA_NOT_READY
│ └── [Poll Attempt 3] ← OK (solution)
└── [Apply Token] ← Inject into form
Instrumentação em Python
Três pacotes cobrem o essencial: a API/SDK do OTel, o exportador OTLP e o instrumentador automático de requests.
Instale as dependências
pip install opentelemetry-api opentelemetry-sdk \
opentelemetry-exporter-otlp \
opentelemetry-instrumentation-requests
Crie os spans de submit e poll
O span pai captcha.solve engloba dois filhos — captcha.submit (a chamada a in.php) e captcha.poll (o laço de consultas a res.php), com um span extra por tentativa. Assim você enxerga, tentativa por tentativa, quanto tempo cada poll levou até o status virar 1:
import os
import time
import requests
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
OTLPSpanExporter,
)
from opentelemetry.sdk.resources import Resource
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from opentelemetry.trace import StatusCode
# Configure provider
resource = Resource.create({"service.name": "captcha-pipeline"})
provider = TracerProvider(resource=resource)
# Export to OTel Collector (or Jaeger/Zipkin directly)
exporter = OTLPSpanExporter(
endpoint=os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT",
"http://localhost:4317")
)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)
# Auto-instrument requests library
RequestsInstrumentor().instrument()
tracer = trace.get_tracer("captchaai.solver")
API_KEY = os.environ["CAPTCHAAI_API_KEY"]
session = requests.Session()
def solve_captcha(sitekey, pageurl, captcha_type="recaptcha_v2"):
"""Solve a CAPTCHA with full OpenTelemetry tracing."""
with tracer.start_as_current_span(
"captcha.solve",
attributes={
"captcha.type": captcha_type,
"captcha.target_url": pageurl,
}
) as solve_span:
# Submit phase
with tracer.start_as_current_span("captcha.submit") as submit_span:
resp = session.post("https://ocr.captchaai.com/in.php", data={
"key": API_KEY,
"method": "userrecaptcha",
"googlekey": sitekey,
"pageurl": pageurl,
"json": 1
})
data = resp.json()
submit_span.set_attribute("http.status_code", resp.status_code)
if data.get("status") != 1:
error = data.get("request", "UNKNOWN")
submit_span.set_status(StatusCode.ERROR, error)
submit_span.set_attribute("captcha.error", error)
solve_span.set_status(StatusCode.ERROR, error)
return {"error": error}
captcha_id = data["request"]
submit_span.set_attribute("captcha.id", captcha_id)
solve_span.set_attribute("captcha.id", captcha_id)
# Poll phase
with tracer.start_as_current_span("captcha.poll") as poll_span:
poll_count = 0
poll_start = time.time()
for _ in range(60):
time.sleep(5)
poll_count += 1
with tracer.start_as_current_span(
f"captcha.poll.attempt",
attributes={"captcha.poll.number": poll_count}
) as attempt_span:
result = session.get(
"https://ocr.captchaai.com/res.php",
params={
"key": API_KEY,
"action": "get",
"id": captcha_id,
"json": 1
}
).json()
if result.get("status") == 1:
attempt_span.set_attribute("captcha.poll.ready", True)
elapsed = time.time() - poll_start
poll_span.set_attribute("captcha.poll.count", poll_count)
poll_span.set_attribute(
"captcha.poll.duration_s", round(elapsed, 2)
)
solve_span.set_attribute(
"captcha.solve_time_s", round(elapsed, 2)
)
solve_span.set_status(StatusCode.OK)
return {
"solution": result["request"],
"elapsed": elapsed,
"polls": poll_count
}
if result.get("request") != "CAPCHA_NOT_READY":
error = result.get("request", "UNKNOWN")
attempt_span.set_status(StatusCode.ERROR, error)
poll_span.set_status(StatusCode.ERROR, error)
solve_span.set_status(StatusCode.ERROR, error)
return {"error": error}
attempt_span.set_attribute("captcha.poll.ready", False)
poll_span.set_attribute("captcha.poll.count", poll_count)
poll_span.set_status(StatusCode.ERROR, "TIMEOUT")
solve_span.set_status(StatusCode.ERROR, "TIMEOUT")
return {"error": "TIMEOUT"}
Instrumentação em Node.js
A mesma estrutura de spans se aplica no Node — só o SDK muda, para a versão server-side do OTel mais o instrumentador HTTP automático.
Instale as dependências
npm install @opentelemetry/api @opentelemetry/sdk-node \
@opentelemetry/sdk-trace-node \
@opentelemetry/exporter-trace-otlp-grpc \
@opentelemetry/instrumentation-http
Crie os spans de submit e poll
Aqui startActiveSpan cuida da propagação de contexto automaticamente — cada span filho já nasce vinculado ao span pai correto, sem passar context manualmente:
const { NodeSDK } = require("@opentelemetry/sdk-node");
const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-grpc");
const { HttpInstrumentation } = require("@opentelemetry/instrumentation-http");
const { trace, SpanStatusCode } = require("@opentelemetry/api");
const axios = require("axios");
// Initialize SDK
const sdk = new NodeSDK({
serviceName: "captcha-pipeline",
traceExporter: new OTLPTraceExporter({
url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4317",
}),
instrumentations: [new HttpInstrumentation()],
});
sdk.start();
const tracer = trace.getTracer("captchaai.solver");
const API_KEY = process.env.CAPTCHAAI_API_KEY;
async function solveCaptchaWithTracing(sitekey, pageurl, captchaType = "recaptcha_v2") {
return tracer.startActiveSpan("captcha.solve", {
attributes: { "captcha.type": captchaType, "captcha.target_url": pageurl },
}, async (solveSpan) => {
try {
// Submit
const captchaId = await tracer.startActiveSpan(
"captcha.submit",
async (submitSpan) => {
try {
const resp = await axios.post("https://ocr.captchaai.com/in.php", null, {
params: {
key: API_KEY, method: "userrecaptcha",
googlekey: sitekey, pageurl, json: 1,
},
});
if (resp.data.status !== 1) {
submitSpan.setStatus({ code: SpanStatusCode.ERROR, message: resp.data.request });
throw new Error(resp.data.request);
}
submitSpan.setAttribute("captcha.id", resp.data.request);
return resp.data.request;
} finally {
submitSpan.end();
}
}
);
solveSpan.setAttribute("captcha.id", captchaId);
// Poll
return await tracer.startActiveSpan("captcha.poll", async (pollSpan) => {
try {
let pollCount = 0;
const pollStart = Date.now();
for (let i = 0; i < 60; i++) {
await new Promise((r) => setTimeout(r, 5000));
pollCount++;
const result = await tracer.startActiveSpan(
"captcha.poll.attempt",
{ attributes: { "captcha.poll.number": pollCount } },
async (attemptSpan) => {
try {
const resp = await axios.get("https://ocr.captchaai.com/res.php", {
params: { key: API_KEY, action: "get", id: captchaId, json: 1 },
});
attemptSpan.setAttribute("captcha.poll.ready", resp.data.status === 1);
return resp.data;
} finally {
attemptSpan.end();
}
}
);
if (result.status === 1) {
const elapsed = (Date.now() - pollStart) / 1000;
pollSpan.setAttribute("captcha.poll.count", pollCount);
solveSpan.setAttribute("captcha.solve_time_s", elapsed);
solveSpan.setStatus({ code: SpanStatusCode.OK });
return { solution: result.request, elapsed, polls: pollCount };
}
if (result.request !== "CAPCHA_NOT_READY") {
throw new Error(result.request);
}
}
throw new Error("TIMEOUT");
} catch (err) {
pollSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
throw err;
} finally {
pollSpan.end();
}
});
} catch (err) {
solveSpan.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
return { error: err.message };
} finally {
solveSpan.end();
}
});
}
module.exports = { solveCaptchaWithTracing };
Configurando o coletor OTel
Em produção, os workers não exportam direto para o Jaeger: eles enviam via OTLP para um coletor, que faz o batching e repassa para um ou mais back-ends. Assim você troca de Jaeger para Datadog (ou adiciona um segundo destino) sem tocar no código da aplicação — só neste YAML:
# otel-collector-config.yaml
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
processors:
batch:
timeout: 5s
exporters:
jaeger:
endpoint: jaeger:14250
tls:
insecure: true
# Or export to Datadog, New Relic, etc.
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [jaeger]
O que os spans revelam sobre o pipeline de CAPTCHA
Cada atributo abaixo aparece no back-end de rastreamento assim que o span correspondente termina:
captcha.type(ex.:recaptcha_v2) — mostra quais tipos de CAPTCHA demoram mais para resolver.captcha.solve_time_s(ex.:24.5) — latência real de resolução, ponta a ponta.captcha.poll.count(ex.:5) — quantas consultas (poll) foram necessárias até o resultado sair.captcha.error(ex.:ERROR_WRONG_CAPTCHA_ID) — detalhamento por tipo de erro.captcha.id(ex.:73519...) — rastreia uma tentativa de resolução específica de ponta a ponta.
Cenário comum para quem opera fora dos EUA: times que rodam workers em sa-east-1 (São Paulo) ou outra região fora dos data centers do provedor costumam ver captcha.solve_time_s mais alto do que o esperado. Para saber se isso é RTT de rede até a API ou tempo de resolução propriamente dito, siga esta ordem:
- Compare
captcha.poll.duration_scomcaptcha.solve_time_s— se a diferença entre os dois for pequena, o polling domina o tempo total. - Se a diferença for grande, o tempo está indo para a chamada inicial de
captcha.submit, antes do primeiropoll. - Repita a medição em horários diferentes — RTT internacional varia bem mais que a latência do próprio solver ao longo do dia.
Problemas comuns e como resolver
- Nenhum trace aparecendo no back-end — o coletor OTel não está em execução. Verifique
docker pse confira a URL do endpoint configurado. - Spans filhos sumindo da árvore — o span não foi encerrado corretamente. Sempre chame
span.end()dentro do blocofinally. - Traces fragmentados em pedaços soltos — o contexto não foi propagado entre spans. Use
startActiveSpanpara propagar o contexto automaticamente. - Aviso de alta cardinalidade no back-end — algum atributo tem valores únicos demais. Não use
captcha.idcomo tag em métricas — só como atributo de span.
Dica: guarde o
otel-collector-config.yamlcomo template do seu time — a mesma configuração serve para instrumentar outros serviços internos, não só o worker de CAPTCHA.
Perguntas frequentes
Dá para instrumentar a API da CaptchaAI sem usar um SDK oficial de OTel?
Sim. Como a API é HTTP puro (in.php/res.php), basta o instrumentador HTTP genérico da sua linguagem (opentelemetry-instrumentation-requests em Python, @opentelemetry/instrumentation-http no Node) mais os spans manuais mostrados acima — não existe nem é necessário um SDK específico da CaptchaAI.
O rastreamento deixa o pipeline mais lento?
Praticamente não. O OTel exporta em lote, de forma assíncrona, e um span amostrado adiciona microssegundos. Para uma resolução de CAPTCHA que já leva de 5 a 120 segundos, esse overhead é irrelevante.
Preciso trocar time.sleep / setTimeout pelo startActiveSpan para o polling funcionar?
Não precisa trocar a lógica de espera — só envolver cada tentativa em tracer.start_as_current_span (Python) ou tracer.startActiveSpan (Node). O sleep/setTimeout entre uma tentativa e outra continua igual; a instrumentação só observa o que já está lá.
Preciso rastrear 100% das resoluções de CAPTCHA?
Em desenvolvimento, sim — ajuda a depurar. Em produção, use amostragem (por exemplo, 10% dos traces) para controlar custo de armazenamento sem perder visibilidade estatística. A exceção: rastreie erros em 100%, sempre.
Qual back-end combina melhor com OTel para um pipeline de CAPTCHA?
Depende do que você já usa — o coletor troca de destino sem exigir mudança de código:
- Já tem Prometheus para métricas? Jaeger cobre bem o lado de traces, sem custo de licença.
- Já paga Datadog ou New Relic para APM? Exportar os spans para lá evita manter mais um sistema de observabilidade.
- Time pequeno, sem back-end ainda? Comece com Jaeger local via Docker — é o caminho mais rápido para ver o primeiro trace.
Próximos passos
Coloque rastreamento distribuído no seu pipeline de CAPTCHA — comece com uma chave de API da CaptchaAI e adicione a instrumentação OpenTelemetry deste guia.
Guias relacionados:
