Recursos
Conexões de banco de dados
O editor SQL consulta os seus próprios bancos PostgreSQL e MySQL ao lado do Orbit SQL: um
administrador cadastra a conexão uma vez, e quem tem um papel com databases.query a escolhe como
origem do editor e escreve o SQL do próprio banco. Toda consulta roda somente leitura e entra na
trilha de auditoria. As rotas e os formatos estão no CONTRACT.md, Adendo v0.24.
Engines com suporte:
- PostgreSQL 12 ou mais recente, Amazon RDS for PostgreSQL e Aurora PostgreSQL;
- MySQL
8.0ou mais recente, MariaDB10.5ou mais recente, Amazon RDS for MySQL e Aurora MySQL.
Antes de começar: ORBIT_SEAL_KEY
O orbit-api guarda a senha e o certificado de CA de cada conexão criptografados com AES-256-GCM,
sob uma chave derivada por HKDF-SHA256 de ORBIT_SEAL_KEY. Sem essa variável ele não guarda senha
nenhuma: as rotas de banco respondem 503 not_configured, GET /api/v1/databases responde
configured: false, e a página Bancos de dados explica como defini-la.
A chave precisa ter pelo menos 32 bytes. Gere-a uma única vez e guarde-a no seu cofre de segredos:
SEAL_KEY=$(openssl rand -base64 48)helm upgrade sreorbit deploy/helm/sreorbit --reuse-values \ --set-string secrets.sealKey="$SEAL_KEY"Quando você não informa secrets.sealKey, o chart mantém a chave que o Secret em uso já guarda,
ou sorteia uma na instalação, e o orbit-api a lê como ORBIT_SEAL_KEY. Uma ferramenta que
renderiza o chart sem o cluster (helm template, Argo CD) sorteia uma chave nova a cada
renderização: nesse caso, defina secrets.sealKey ou mantenha o Secret por conta própria. Se você mantém o Secret por conta própria, acrescente nele a chave
ORBIT_SEAL_KEY. Com outra chave, toda senha guardada fica ilegível: não há rotação de chave,
então depois de uma troca um administrador digita de novo a senha de cada conexão.
Um usuário somente leitura
O editor é somente leitura em três camadas, e a última é sua:
- O
orbit-apiconfere a instrução antes de tocar no banco: exatamente uma instrução, cuja primeira palavra-chave éSELECT,WITH,EXPLAIN,SHOW,VALUES,TABLE,DESCRIBEouDESC, nenhuma palavra-chave de escrita fora de aspas e comentários, e nenhuma das funções que mexem no servidor (pg_terminate_backend,pg_read_file,dblink,set_config,load_file,get_lock, todo lockpg_*advisory*e o resto da lista do contrato). Uma leitura que trava linhas também é recusada:FOR UPDATEeFOR NO KEY UPDATEcomo escritas,FOR SHARE,FOR KEY SHAREeLOCK IN SHARE MODEporque o MySQL aplica os locks de linha dentro de uma transação somente leitura, e um advisory lock do PostgreSQL sobrevive à transação na conexão do pool. Uma recusa é400 sql_errore diz o que foi recusado. - Cada consulta roda em uma transação somente leitura, desfeita logo depois.
- O usuário do banco só consegue ler. Crie um para o Orbit, e que nada mais o use.
PostgreSQL, com um usuário que pode criar papéis (no RDS, o usuário master):
CREATE ROLE orbit_ro LOGIN PASSWORD 'change-me';
GRANT CONNECT ON DATABASE orders TO orbit_ro;
GRANT USAGE ON SCHEMA public TO orbit_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO orbit_ro;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO orbit_ro;
ALTER ROLE orbit_ro SET default_transaction_read_only = on;MySQL e MariaDB:
CREATE USER 'orbit_ro'@'%' IDENTIFIED BY 'change-me';
GRANT SELECT, SHOW VIEW ON orders.* TO 'orbit_ro'@'%';Troque orders pelo seu banco e change-me por uma senha gerada. Repita as linhas de GRANT
para cada schema ou banco que o editor deve enxergar.
O teste de conexão avisa quando o usuário consegue escrever. No PostgreSQL isso é um superusuário,
qualquer permissão de INSERT, UPDATE, DELETE ou TRUNCATE em
information_schema.role_table_grants, ou CREATE no banco; no MySQL é INSERT, UPDATE,
DELETE, CREATE, DROP, ALTER ou ALL em SHOW GRANTS. A página então avisa em vermelho.
Salvar continua permitido, e as duas primeiras camadas continuam valendo, mas corrija isso.
Cadastrando uma conexão
Administração → Bancos de dados (/deck/admin/databases, sob settings.manage) lista as conexões
e cadastra, edita, testa e exclui cada uma. O formulário pede:
- um nome, de 1 a 80 caracteres e único, que é como o editor a lista;
- o engine, o host, a porta, o banco e o usuário;
- a senha, que nunca é exibida de novo, nunca vai para log nem para a auditoria; numa edição,
deixá-la vazia mantém a guardada, a menos que a edição mude o engine, o host, a porta, o usuário,
o modo de TLS ou a CA: a senha guardada só vai para o servidor para o qual foi digitada, então essa
edição pede a senha de novo (400
invalid_request). A senha do usuário de monitoramento segue a mesma regra; - o modo de TLS, e um certificado de CA opcional em PEM para um banco assinado por uma CA privada;
- quem pode consultá-la: os papéis marcados aqui ou, sem nenhum marcado, todo papel que tem
databases.query. Um papel fora da lista nem vê a conexão. Um papel também pode listar as conexões que alcança, em Administração → Papéis: veja "Um papel para um time de bancos".
Salvar testa a conexão antes, com timeout de 10 s e SELECT 1, e recusa com o motivo dado pelo
banco quando o teste falha. O orbit-api resolve o host antes de cada conexão e recusa um que
resolva para um endereço link-local ou de metadados da nuvem (169.254.0.0/16, fe80::/10,
fd00:ec2::254, fd00:ec2::23, 168.63.129.16, 100.100.100.200), não especificado, multicast ou broadcast: nenhum
banco mora ali, e o serviço de metadados entrega as credenciais do node. Um endereço de loopback,
privado (10/8, 172.16/12, 192.168/16, fc00::/7) ou compartilhado (100.64/10) também é
recusado, a menos que você marque Em rede privada na conexão: marque para um banco no cluster, na
sua VPC ou atrás de um proxy sidecar. O orbit-api resolve o nome uma vez por conexão e conecta no
endereço que conferiu, então um nome que muda de resposta logo depois não alcança nada novo. Criar, alterar e excluir uma conexão ficam na auditoria como
database.create, database.update (com os nomes dos campos que mudaram) e database.delete,
com o tipo de alvo database.
Modos de TLS:
| Modo | O que faz |
|---|---|
verify-full | O padrão. Criptografado, com o certificado e o hostname verificados contra as raízes públicas, o pacote global de CAs do Amazon RDS e a CA que você informou |
require | Criptografado, sem verificar o certificado |
disable | Texto puro: a senha e cada resultado atravessam a rede sem criptografia |
Amazon RDS e Aurora
verify-fullfunciona como está: oorbit-apitraz o pacote global de CAs do RDS, então nenhuma CA é necessária.- O security group do banco precisa liberar o
orbit-apina porta do banco: a partir do security group dos nodes de trabalho, ou do security group do próprio pod quando você usa security groups para pods. - A NetworkPolicy do chart só deixa o
orbit-apisair para onde ele precisa. Acrescente a faixa de endereços do banco, com a porta, emcomponents.orbit-api.databases.egress:
components:
orbit-api:
databases:
egress:
- cidr: 192.0.2.0/24
ports: [5432, 3306]Use a faixa privada da VPC, ou as faixas das subnets do banco para uma regra mais estreita. Sem uma entrada, o teste de conexão falha por timeout, porque a política descarta os pacotes.
Consultando
No editor SQL, o seletor de origem lista primeiro o SRE Orbit e depois as conexões que você pode consultar. Em uma conexão:
- o SQL é o dialeto do próprio banco, executado nele, e a resposta tem o mesmo formato do Orbit SQL, então a grade, o gráfico e a exportação em CSV funcionam sem mudança;
- o painel de schema e o autocompletar vêm do
information_schemado banco, sem os schemas de sistema: no máximo 2.000 tabelas e 20.000 colunas, em cache por 5 minutos; - a galeria de exemplos e "Escrever com o Nocturne" ficam ocultos: foram escritos para as tabelas do Orbit;
- uma consulta salva guarda a sua conexão, e um link compartilhado a leva junto.
Subconsultas funcionam como cada banco as executa: IN (SELECT ...), EXISTS e NOT EXISTS,
tabelas derivadas no FROM, subconsultas escalares na lista de colunas ou numa comparação, ANY e
ALL, LATERAL no PostgreSQL, e WITH, recursivo ou não. A instrução continua sendo uma só, na
transação somente leitura, dentro do limite de tempo, e as mesmas palavras são recusadas dentro de
uma subconsulta e fora dela.
Os tipos voltam como os seis do Orbit SQL: inteiros como int (como string além de ±2^53),
real, double e numeric como float, bool, datas e horários como timestamp em UTC,
json, jsonb e arrays como json, e todo o resto como string, com bytea em hexadecimal.
NULL é null.
Limites:
- uma consulta devolve 1.000 linhas a menos que você aumente, até 10.000, e avisa quando foi truncada;
- ela pode rodar por 30 s, ou até 60 s se você permitir; passado isso, o banco e o
orbit-apia cancelam e a resposta é408 timeout; - uma célula de texto para em 64 KiB, e uma resposta acima de 32 MiB é
413 too_large; - uma conexão roda no máximo 2 consultas ao mesmo tempo, e o
orbit-apino máximo 4 somando todas.
Erros: o erro do próprio banco é 400 sql_error, com a posição quando o PostgreSQL a informa; uma
falha de conexão, de TLS ou de autenticação é 502 database_unreachable com o motivo, nunca a
senha; uma conexão desconhecida, ou que o seu papel não enxerga, é 404 not_found.
Toda consulta em uma conexão, com sucesso ou falha, fica na auditoria como database.query contra
aquela conexão, com os primeiros 4 KiB do SQL, as linhas, se foi truncada, o tempo que levou e, na
falha, o erro.
Nocturne em um banco
O Nocturne responde perguntas sobre os dados de uma conexão, não só sobre o cluster: ele lê as
tabelas e colunas da conexão, escreve um SELECT no dialeto daquele banco e lê a resposta. Ele
roda como a pessoa que pergunta, nunca com credenciais próprias, e só onde um admin abriu a conexão
para ele. As rotas e os formatos estão no CONTRACT.md, Adendo nocturne-db.
Quem pode. Uma pessoa cujo papel tem nocturne.use e databases.query, em uma conexão que o
papel dela pode consultar (o "Quem pode consultar" da conexão). Sem uma das duas permissões, a rota
de consulta responde 403 forbidden; com o recurso nocturne desligado ou fora do plano, 403 feature_disabled ou 403 plan_required.
Abrindo uma conexão para o Nocturne. Toda conexão começa fechada. Em Admin > Bancos de dados, o
interruptor da coluna Nocturne abre uma (settings.manage), e o link ao lado lista os nomes de
coluna que o Nocturne sempre mascara ali, além das regras dele, um por linha. Uma conexão fechada
responde 403 nocturne_off, e o Nocturne diz à pessoa a quem pedir. Cada mudança fica na auditoria
como database.nocturne. No Aurora ou com uma réplica de leitura, cadastre uma segunda conexão no
endpoint de leitura (o endpoint cluster-ro-, ou o da réplica) e abra só essa: assim as consultas
do Nocturne nunca rodam no writer.
O que o Nocturne mascara
A resposta segue para o provedor do modelo, um terceiro, então o orbit-api a mascara antes que
ela saia, e a pessoa vê no chat a mesma resposta mascarada:
- Pela coluna. Uma coluna é mascarada inteira (
[masked]) quando o nome dela, ou o nome da coluna de tabela de onde ela vem, indica dado pessoal ou segredo: e-mail, telefone, celular, WhatsApp, CPF, CNPJ, RG, CNH, SSN, NIF, passaporte, documento, IBAN, número de cartão, CVV, PAN, password, passphrase, passcode,*_pass, senha, secret, segredo, token, bearer, signature, salt, pepper, OTP, PIN, qualquer*_key, chave de API, chave de acesso, chave privada, chave, credenciais,*_creds, autenticação básica, authorization e identificadores fiscais e nacionais. A coluna de origem é a que o banco informa para cada coluna do resultado, entãoSELECT email AS contacttambém é mascarado. Quando a instrução cita uma coluna assim, ou seleciona todas as colunas com*, uma coluna de texto calculada ou renomeada no caminho (upper(email), a lista de colunas de uma CTE) também é mascarada inteira. - Pelo valor, em todas as outras células, JSON incluído: um e-mail (
[email]), um CPF ou CNPJ formatado ou só em dígitos com dígito verificador válido ([cpf],[cnpj]), um RG ([document]), um número de cartão que passa no teste de Luhn ([card]), um telefone escrito com+, parênteses ou separadores, ou um celular brasileiro só em dígitos ([phone]), um hash bcrypt, Argon2 ou PBKDF2, uma string hexadecimal de 32 caracteres ou mais, um token de 24 caracteres com maiúsculas, minúsculas e dígitos ([secret]), e os formatos de credencial que as ferramentas do cluster já ocultam (JWTs, tokens bearer, chaves da AWS, chaves privadas, a senha de uma string de conexão,password=...). Uma chave de JSON que indica dado sensível mascara o seu valor. - Os nomes do admin, comparados sem diferenciar maiúsculas, mascaram uma coluna inteira.
- Erros. Um erro do banco pode citar um valor (
Duplicate entry '...'): a mensagem é mascarada do mesmo jeito antes de sair. O SQL em si é do próprio modelo e não é mascarado.
O mascaramento lê nomes e formatos; ele não tem como saber que uma coluna chamada notes guarda o
endereço de um cliente. Acrescente colunas assim à lista da conexão.
O que impede uma consulta de deixar o banco lento
Antes que o banco execute a instrução, o orbit-api:
- a submete ao mesmo filtro de instruções do editor SQL, e só a
SELECTouWITH, sem leitura com trava (FOR SHARE,LOCK IN SHARE MODE) e semsleep,benchmark,pg_sleep,get_locknem as funções de advisory lock; - dá a ela um
LIMITde 200 linhas, ou mantém um menor, e recusa umOFFSETacima de 100.000 linhas; - lê o plano com
EXPLAIN FORMAT=JSON(MySQL) ouEXPLAIN (FORMAT JSON)(PostgreSQL), nuncaANALYZE, e o recusa com400 plan_refusedquando ele leria mais de 100.000 linhas de uma tabela (uma varredura completa, uma varredura completa de índice, o lado interno de um join uma vez por linha externa), ordenaria, faria hash ou montaria uma tabela temporária de mais de 100.000 linhas, ou leria mais de 100.000 linhas no total. A recusa diz qual tabela, quantas linhas e os índices dessa tabela, para o modelo reescrever a consulta sobre uma coluna indexada. No PostgreSQL, o tamanho de uma varredura completa é oreltuplesda tabela, e uma varredura sem filtro sob umLIMITpequeno conta as linhas que devolve; - roda uma consulta do Nocturne por vez em cada conexão (uma segunda espera até 2 s, depois
429 busy), por no máximo 5 s, cancelada pelo banco e peloorbit-apidepois disso, na mesma transação somente leitura que o editor SQL usa.
O plano do MySQL não mostra que um LIMIT interrompe uma varredura de tabela, então SELECT * FROM big LIMIT 10 é recusado no MySQL; ordenar por uma coluna indexada (ORDER BY id DESC LIMIT 10)
passa.
As 100.000 linhas e os 5 s vêm de uma medição no MySQL 8.4 e no PostgreSQL 16 em Docker com 2 CPUs,
uma tabela de 4.000.000 de linhas e uma carga constante de leituras e escritas indexadas ao lado das
consultas. O que as proteções fizeram com essa carga:
Ao lado de 400 leituras e escritas pontuais por segundo (80% leituras, 8 conexões), dois fluxos de
instruções rodaram ao mesmo tempo, cada um pausando 1 s entre as instruções, como fazem os turnos de
um modelo; cada execução durou 60 s, três execuções por linha no MySQL e duas no PostgreSQL,
intercaladas, e a tabela traz a mediana delas. O p95 é o da carga de fundo medido pelo cliente dela;
"p95 do próprio MySQL" é o QUANTILE_95 da leitura pontual no performance_schema, que deixa de
fora o cliente e a rede.
| Execução | p95 no MySQL | p99 no MySQL | p95 do próprio MySQL | p95 no PostgreSQL | O que os fluxos fizeram |
|---|---|---|---|---|---|
| Nada além da carga | 2,48 ms | 2,93 ms | 0,263 ms | 2,59 ms | - |
| Perguntas típicas, pelas proteções | 2,58 ms (+4%) | 2,88 ms | 0,251 ms (-5%) | 2,25 ms (-13%) | cada uma leu menos de 100.000 linhas; 360 respondidas no MySQL |
| O mesmo sem pausa | 2,31 ms (-7%) | 2,73 ms | 0,251 ms (-5%) | 2,16 ms (-17%) | 12.815 respondidas no MySQL, uma por vez |
| Varreduras completas e ordenações das 4.000.000 de linhas, sem proteções (o caminho do editor SQL) | 3,27 ms (+32%) | 5,34 ms (+82%) | 0,316 ms (+20%) | 4,35 ms (+68%) | cada uma rodou cerca de 1,6 s no MySQL e 0,6 s no PostgreSQL, com os workers paralelos dele, duas ao mesmo tempo |
| As mesmas instruções, pelas proteções | 2,22 ms (-11%) | 2,62 ms | 0,263 ms (+0%) | 2,36 ms (-9%) | todas recusadas pelo plano, em cerca de 7 ms |
As linhas de base variaram de 2,26 a 2,60 ms no MySQL e de 2,35 a 2,76 ms no PostgreSQL: uma mudança abaixo de uns 10% é ruído desta máquina, e toda linha com proteções fica dentro dele ou abaixo da linha de base. Toda execução sem proteções (3,25 a 3,51 ms no MySQL, 4,21 a 4,48 ms no PostgreSQL) ficou acima de toda linha de base, e o p99 do PostgreSQL foi de 2,99 a 6,98 ms.
Antes disso, uma instrução a cada 2 s que lia 10.000, 100.000, 1.000.000 ou 4.000.000 de linhas levou 6, 39, 328 e 1.343 ms do tempo do banco cada uma no MySQL. Ao lado delas, o p95 da carga de fundo mudou +27%, +14%, +12% e +5%: sem ordem pelo tamanho, porque uma instrução por vez usa no máximo uma CPU. O que o tamanho muda é por quanto tempo cada instrução ocupa essa CPU, e com as proteções uma instrução aceita lê no máximo 100.000 linhas, cerca de 40 ms aqui. O limite de 5 s é para um plano que engana a verificação: a varredura completa mais lenta aqui levou cerca de 1,6 s. Um mesmo valor serve aos dois bancos, então nenhum dos dois limites é uma configuração. Os bancos rodaram em Docker com 2 CPUs dedicadas, o MySQL com um buffer pool de 1 GiB e o PostgreSQL com 1 GiB de shared buffers, ambos com a tabela em memória, e confirmando sem um fsync por commit para que a oscilação do disco compartilhado não abafasse as consultas. Uma tabela maior que a memória faz uma varredura ler também o disco, o que estas execuções não mostram.
Toda consulta do Nocturne fica na auditoria como database.nocturne.query contra a conexão: a
pessoa, os primeiros 4 KiB do SQL como rodou (com o seu LIMIT), o veredito do plano, as linhas,
se foram cortadas, quantos valores foram mascarados, o tempo e o resultado. Uma recusa antes de o
banco executar a instrução tem resultado denied, com o motivo; um erro do banco é failure.
Pela API
| Rota | Requer | Corpo e resposta |
|---|---|---|
GET /api/v1/databases | databases.query ou settings.manage | {configured, databases} |
POST /api/v1/databases | settings.manage | A conexão e a sua password → 201 {database, test} |
PUT /api/v1/databases/{id} | settings.manage | O mesmo corpo → {database, test} |
DELETE /api/v1/databases/{id} | settings.manage | 204 |
POST /api/v1/databases/{id}/test | settings.manage | {ok, serverVersion, readOnly, elapsedMs} ou {ok, error} |
GET /api/v1/databases/{id}/schema | databases.query | {tables, truncated} |
POST /api/v1/sql/query | databases.query | {sql, limit, timeoutMs, database} → {columns, rows, stats} |
POST /api/v1/sql/explain | databases.query | {sql, database} → {plan} |
GET /api/v1/databases/nocturne | databases.query ou settings.manage | {databases: [{id, name, engine, enabled, maskColumns}]} |
PUT /api/v1/databases/{id}/nocturne | settings.manage | {enabled, maskColumns} → {id, enabled, maskColumns} |
POST /api/v1/databases/{id}/nocturne/query | databases.query e nocturne.use | {sql} → {columns, rows, stats, sql, limit, timeoutMs, plan, masked} |
Quem chama tendo só databases.query vê cada conexão como {id, name, engine, database}.
Dados de demonstração
A demonstração pública tem uma conexão, demo-shop, marcada como PostgreSQL: uma loja com cerca de
200 clientes, 50 produtos e 2.000 pedidos nos últimos 90 dias, nas tabelas customers,
products, orders e order_items. Os exemplos dela abrem no editor quando ela é a origem.
Cadastrar, alterar e testar conexões fica desligado na demonstração.
Monitoramento de desempenho
O orbit-api acompanha uma conexão MySQL como o Performance Insights e o Datadog Database
Monitoring fazem, a partir do performance_schema: quais instruções ocupam o tempo do banco,
quantas sessões estão ativas e pelo que cada uma espera. Funciona no Amazon RDS for MySQL 8.0 e
8.4, no Aurora MySQL 3 e no MySQL 8.0 ou mais recente que você mesmo opera. O PostgreSQL fica de
fora: salvar uma conexão PostgreSQL com o monitoramento ligado responde 400. As rotas e os
formatos estão no CONTRACT.md, Adendo v0.28.
O monitoramento entra com um segundo usuário do banco, nunca o do editor SQL: ele lê as instruções de todas as sessões, e o usuário do editor não pode lê-las.
No plano Free o coletor roda e o Deck mostra a carga do banco, as chamadas, a latência e os erros. O
texto de cada instrução, as sessões ao vivo, o EXPLAIN e os valores de uma instrução precisam de
uma chave Enterprise: as rotas
deles respondem 403 plan_required até uma chave entrar. Veja docs/licensing.md.
O que o Orbit guarda, e o que nunca guarda
O Orbit guarda:
- contadores por digest de instrução e por espera, no
/metricsdoorbit-api, que o orbit-agent já coleta comojob="sreorbit",component="orbit-api"para oorbit-stack; - o texto que o MySQL normalizou para cada digest (
DIGEST_TEXT, com cada literal trocado por?), só na memória doorbit-api: no máximo 2.000 por conexão, saindo primeiro o visto há mais tempo, e perdidos num restart até a próxima leitura; - as sessões ativas do último segundo, na memória.
O Orbit nunca guarda, registra em log ou exporta o texto literal de uma instrução:
QUERY_SAMPLE_TEXT, SQL_TEXT e PROCESSLIST_INFO. O coletor nunca seleciona essas colunas. O
EXPLAIN lê o QUERY_SAMPLE_TEXT de um digest quando você pede o plano dele, executa o EXPLAIN,
troca por ? os literais das condições do plano e descarta a amostra; a linha de auditoria leva o
digest e o schema. Quem tem databases.raw_sql pode pedir as instruções de um digest com os
valores (abaixo): elas vão para a resposta desse leitor e para nenhum outro lugar. O teste de integração roda instruções com uma string marcadora e procura essa
string no /metrics, em cada linha de log, na trilha de auditoria e nas respostas das rotas.
As séries, todas na porta de métricas do orbit-api:
| Série | Labels | Origem |
|---|---|---|
orbit_dbm_up | db | 1 enquanto a conexão do coletor responde, senão 0 |
orbit_dbm_performance_schema | db | @@performance_schema |
orbit_dbm_query_calls_total | db, schema, digest | COUNT_STAR |
orbit_dbm_query_seconds_total | db, schema, digest | SUM_TIMER_WAIT / 1e12 |
orbit_dbm_query_lock_seconds_total | db, schema, digest | SUM_LOCK_TIME / 1e12 |
orbit_dbm_query_cpu_seconds_total | db, schema, digest | SUM_CPU_TIME / 1e12, no 8.0.28 ou mais recente com o consumer events_statements_cpu ligado |
orbit_dbm_query_errors_total | db, schema, digest | SUM_ERRORS |
orbit_dbm_query_rows_sent_total | db, schema, digest | SUM_ROWS_SENT |
orbit_dbm_query_rows_examined_total | db, schema, digest | SUM_ROWS_EXAMINED |
orbit_dbm_query_rows_affected_total | db, schema, digest | SUM_ROWS_AFFECTED |
orbit_dbm_query_no_index_total | db, schema, digest | SUM_NO_INDEX_USED |
orbit_dbm_query_full_scans_total | db, schema, digest | SUM_SELECT_SCAN |
orbit_dbm_query_tmp_disk_tables_total | db, schema, digest | SUM_CREATED_TMP_DISK_TABLES |
orbit_dbm_active_seconds_total | db, wait | Amostras de 1 s: os segundos que cada sessão ativa passou, sob a sua espera |
orbit_dbm_query_active_seconds_total | db, schema, digest | As mesmas amostras, por digest de instrução |
orbit_dbm_collect_errors_total | db, stage | Etapas que falharam: connect, consumers, digests, activity |
orbit_dbm_sampled_seconds_total | db | Segundos que a amostragem de sessões de 1 s cobriu, os passos somados |
orbit_dbm_digests_read_timestamp_seconds | db | Hora Unix da última leitura da tabela de digests: os contadores por digest guardam os valores do MySQL dessa hora |
db é o id da conexão, schema o schema padrão da instrução ("" quando não há) e digest o
digest de 64 caracteres hexadecimais do MySQL. Só os ORBIT_DBM_TOP_DIGESTS digests de maior tempo
total (padrão 100, de 1 a 1.000) ganham séries por digest, então uma conexão acrescenta cerca de 12
séries por digest e mais uma por espera vista. As séries _total leem os contadores do próprio
MySQL: quando o MySQL zera a tabela de digests ou reinicia, rate() e increase() tratam o reset.
rate(orbit_dbm_active_seconds_total[5m]) é a média de sessões ativas, o que o Performance
Insights chama de DB load:
sum by (wait) (rate(orbit_dbm_active_seconds_total{db="db_7Hq2..."}[5m]))
topk(10, sum by (schema, digest) (rate(orbit_dbm_query_seconds_total{db="db_7Hq2..."}[5m])))As instruções do próprio provedor
O RDS e o Aurora rodam o heartbeat, as verificações de réplica e as métricas como rdsadmin, e
numa instância calma esse trabalho pode ser metade das chamadas. O Orbit esconde por padrão o que
uma conta de cliente não consegue rodar ali e as leituras de catálogo de uma sessão sem schema
padrão:
- o tempo ativo de toda sessão do
rdsadminemorbit_dbm_active_seconds_total; - toda série por digest de uma instrução que nenhuma conta de cliente consegue rodar naquela instância, enquanto nenhuma chamada dela falhou;
- toda série por digest de uma leitura de catálogo rodada sem schema padrão, enquanto nenhuma
chamada dela falhou: um
SHOW, ou umSELECTde tabelas doperformance_schema, doinformation_schema, domysqlou dosys, ou de variáveis@@GLOBALou@@aurora_*, que não cite outro schema. Uma leitura de variável de sessão comoSELECT @@session.transaction_read_only, que os drivers rodam a cada empréstimo de conexão, aparece. O Performance Insights lê assim a tabela de digests, as variáveis@@GLOBALe as viewsinformation_schema.rds_*. A sua aplicação conecta com o banco dela como padrão, então as instruções dela levam esse schema e aparecem; a mesma leitura feita do seu cliente SQL sem banco selecionado some junto com as do provedor.
| Instrução | Por que nenhuma conta de cliente a roda |
|---|---|
INSERT, REPLACE, UPDATE ou DELETE numa tabela mysql.rds_*, como o heartbeat | A AWS trava o schema mysql contra escrita no Aurora MySQL 3 e no RDS for MySQL 8.0.36 em diante. Num RDS for MySQL mais antigo, elas aparecem. |
SET @@sql_log_bin, SET sql_log_bin | Uma variável de sessão restrita: exige SUPER, SYSTEM_VARIABLES_ADMIN ou SESSION_VARIABLES_ADMIN, e a AWS não dá nenhum deles a uma conta de cliente. |
PURGE BINARY LOGS | Exige SUPER ou BINLOG_ADMIN, que a AWS também não dá a nenhuma conta de cliente. |
SET LOCAL oscar_local_only_replica_host_status, SET @@aurora_enable_dd_access | O Aurora responde a uma sessão de cliente com o erro 1193, variável de sistema desconhecida. |
Essas séries levam internal="true". Uma chamada que falhou pode ser uma tentativa de cliente,
então um digest com erro aparece a partir da leitura seguinte. Todo o resto aparece, rode quem
rodar: COMMIT, SELECT ?, um SELECT só de funções como GET_LOCK ou SLEEP, e qualquer
instrução rodada com um schema padrão.
O coletor deixa as próprias instruções fora dos principais digests: ele conecta com o
performance_schema como schema padrão e descarta todo digest desse schema. Descarta também o
EXPLAIN FORMAT=JSON, que a ação Explicar do Deck roda (e o seu, se a sua aplicação rodar um).
As instruções em volta desse plano (SET SESSION MAX_EXECUTION_TIME, START TRANSACTION READ ONLY, ROLLBACK) e as consultas do editor SQL rodam como o usuário do editor no seu schema e
aparecem, como as de qualquer cliente.
O coletor trata a conexão como RDS quando o host termina em .rds.amazonaws.com ou
.rds.amazonaws.com.cn, e como Aurora quando SELECT @@aurora_version responde; a versão vem de
VERSION() (uma versão do MariaDB nunca conta como 8.0.36 ou posterior) e de @@aurora_version. Em
qualquer outro MySQL, Cloud SQL e Azure Database for MySQL incluídos, nada leva o label. Nada é
aprendido nem guardado: cada leitura decide pelo texto e pela contagem de erros do digest, então um
restart do orbit-api não muda nada. O label de um digest muda na primeira chamada que falha, e
volta quando o MySQL zera a tabela de digests (um restart ou um TRUNCATE), porque a contagem de
erros recomeça em 0. O Deck junta os labels de um digest, então nenhuma chamada cai entre eles.
O Deck deixa as séries marcadas fora dos cartões, da carga do banco por espera, de Principais SQL e
das sessões ao vivo, na lista de bancos e na página de cada conexão, até você ligar Mostrar
instruções do provedor (rdsadmin) (internal=1 na URL). Uma consulta sua faz o mesmo com
internal!="true":
sum by (schema, digest) (rate(orbit_dbm_query_calls_total{db="db_7Hq2...",internal!="true"}[5m]))O Deck lê esses contadores brutos e nunca tira média de passos de rate(), que sobem em rampa por
uma janela de rate inteira depois que os dados começam:
- Chamadas, tempo e erros por segundo são quanto cada contador cresceu entre a primeira e a última
leitura de digests na janela, sobre os segundos entre essas leituras
(
orbit_dbm_digests_read_timestamp_seconds). Um buraco na coleta entre elas conta, porque o MySQL continua contando durante ele. Uma instrução vista pela primeira vez depois da primeira leitura (ofirstSeenMsdo digest) e no máximo na primeira leitura dela conta desde a primeira chamada, porque o contador dela começou em zero dentro da janela; uma mais antiga que entrou nos principais digests depois conta só desde a primeira leitura. Depois de um reinício do MySQL ou de umTRUNCATEda tabela de digests, ofirstSeenMspassa para a primeira chamada desde então, depois da primeira leitura da instrução: a queda do contador conta como um reinício, e só as chamadas desde ele somam. Um failover do Aurora leva o endpoint para uma instância com contadores próprios e umfirstSeenMsde antes da queda: essa queda não soma chamadas. Se o contador da nova instância for maior que o da antiga, a página lê a diferença como chamadas e as taxas daquela janela saem altas. As taxas da página da frota e os gráficos de uma instrução contam toda queda como reinício. - As amostras que um orbit-api anterior a essas duas séries gravou valem no horário do passo, e a amostragem de sessões conta como rodando de um desses passos ao seguinte.
- A carga, a da página e a de cada instrução, é o crescimento dos segundos ativos sobre o
crescimento de
orbit_dbm_sampled_seconds_total: um tempo em que a amostragem de sessões não rodou não é carga nem tempo.
A página diz qual tempo as leituras cobrem: um coletor que começou 11 minutos antes do fim de uma janela de 1 hora mostra as taxas desses 11 minutos.
Pelo que uma sessão espera
A cada segundo o coletor lê as sessões de primeiro plano, fora a dele, que não estão ociosas
(Sleep) nem são daemons, e conta cada uma sob um único wait:
wait | Quando |
|---|---|
row_lock | A sessão tem um pedido de lock de linha do InnoDB pendente em performance_schema.data_lock_waits. Um label do próprio Orbit, de propósito fora dos nomes de instrumento do MySQL. |
Um evento de espera, como wait/io/table/sql/handler | A última espera da sessão em events_waits_current ainda está em andamento. |
CPU | Qualquer outro caso: a última espera terminou, então a sessão está executando. |
Medido no MySQL 8.4.11 com os instrumentos padrão, e de novo com todo instrumento wait/% ligado:
uma sessão travada num lock de linha aparece em events_waits_current como
wait/io/table/sql/handler, o mesmo nome que um full scan de tabela mostra enquanto lê linhas. O
row_lock separa os dois casos. Com os instrumentos padrão, um SELECT SLEEP() aparece como CPU.
Custo no banco
O performance_schema reserva a maior parte da memória dele quando o MySQL sobe. Medido na imagem
mysql:8.4 (MySQL 8.4.11) no Docker com --cpus 1 e max_connections 151, como a memória do
container depois de um restart (docker stats) e como a contagem do próprio performance_schema
(SELECT SUM(CURRENT_NUMBER_OF_BYTES_USED) FROM performance_schema.memory_summary_global_by_event_name WHERE EVENT_NAME LIKE 'memory/performance_schema/%'):
| Configuração | Memória do container | Contagem do performance_schema |
|---|---|---|
performance_schema = OFF | 192 MiB | 0 |
| Ligado, todo tamanho no padrão | 436 MiB (+244) | 224,5 MiB |
Ligado, os quatro *_history_long_size em 0 | 382 MiB (+189) | 183,9 MiB |
Ligado, os três comprimentos em 4096 | 570 MiB (+378) | 342,4 MiB |
Com max_connections 60 no lugar de 151, nenhum desses números mudou.
db.t4g.micro (1 GiB): deixe o
performance_schemadesligado. Por padrão o RDS dá ao buffer pool do InnoDB três quartos da memória da instância, e 189 MiB ou mais por cima deixam uma instância de 1 GiB sem memória. Na db.t4g.small (2 GiB), ligue-o com os quatro parâmetros*_history_long_sizeem 0. Da db.t4g.medium para cima, os tamanhos padrão. Ponha os três comprimentos em4096só com memória sobrando: eles mantêm inteiras as instruções de até 4 KiB, por mais 134 MiB.
O custo do próprio coletor, medido no mesmo container. O tempo de servidor por consulta é a
contagem do próprio MySQL para as instruções do coletor (AVG_TIMER_WAIT, QUANTILE_95 e
MAX_TIMER_WAIT em events_statements_summary_by_digest):
| Consulta | A cada | Ocioso | 10 sessões num lock de linha | Tabela de digests cheia (9.999) |
|---|---|---|---|---|
| Sessões ativas | 1 s | 0,82 ms de média, 2,2 ms de máximo | 2,1 ms de média, 5,9 ms de máximo | 1,4 ms de média, 6,8 ms de máximo |
| Os 100 digests do topo | 10 s | 1,1 ms de média | 1,5 ms de média | 20 ms de média, 69 ms de máximo |
setup_consumers | 10 s | 0,34 ms de média | 0,42 ms de média | 0,38 ms de média |
O orbit-api (build release, lendo um cluster k3d pequeno) contra esse container: 38 MiB de memória e 0,05% de um núcleo sem
nenhuma conexão monitorada; 40 MiB e 0,18% com uma; 44 MiB e 1,0% com sete (45 MiB e 0,6% com a
carga rodando), cada número em 60 s lidos do /proc.
1. O parameter group
Todo parâmetro abaixo é estático: passa a valer quando a instância reinicia. Ponha
performance_schema em 1 explicitamente. Um parameter group que mostra 0 com Source system
continua desligado, com Performance Insights ou sem, e a verificação lê o próprio
@@performance_schema.
RDS for MySQL 8.4 (família mysql8.4), no DB parameter group da própria instância:
| Parâmetro | Valor | Quando |
|---|---|---|
performance_schema | 1 | Sempre |
performance_schema_events_statements_history_long_size | 0 | db.t4g.small |
performance_schema_events_waits_history_long_size | 0 | db.t4g.small |
performance_schema_events_stages_history_long_size | 0 | db.t4g.small |
performance_schema_events_transactions_history_long_size | 0 | db.t4g.small |
max_digest_length, performance_schema_max_digest_length, performance_schema_max_sql_text_length | 4096 | Opcional, com memória sobrando; uma instrução além de 1.024 bytes de tokens fica sem ligação com traces |
O RDS for MySQL não tem parâmetro para os consumers, e um reboot desliga o events_waits_current.
A procedure do passo 2 os liga, e o Orbit a chama toda vez que conecta.
Aurora MySQL 3 (família aurora-mysql8.0), no DB parameter group da instância, não no do
cluster:
| Parâmetro | Valor |
|---|---|
performance_schema | 1 |
performance_schema_consumer_events_statements_current | 1 |
performance-schema-consumer-events-waits-current | ON (grafado com hífens, valores ON e OFF) |
performance_schema_consumer_statements_digest | 1 |
performance_schema_consumer_global_instrumentation | 1 |
performance_schema_consumer_thread_instrumentation | 1 |
O Aurora MySQL 3.08 não tem parâmetro para o events_statements_cpu, do qual depende o tempo de CPU
por digest: crie lá também a procedure do passo 2, e o Orbit o liga.
No MySQL que você mesmo opera, no my.cnf sob [mysqld], depois reinicie o mysqld:
performance_schema = ON
performance-schema-consumer-events-statements-current = ON
performance-schema-consumer-events-waits-current = ON
performance-schema-consumer-statements-digest = ON
performance-schema-consumer-events-statements-cpu = ON2. O usuário de monitoramento
Como o usuário administrador (no RDS, o usuário master), no writer:
CREATE USER 'orbit_monitor'@'%' IDENTIFIED BY 'change-me';
GRANT SELECT ON performance_schema.* TO 'orbit_monitor'@'%';
ALTER USER 'orbit_monitor'@'%' WITH MAX_USER_CONNECTIONS 5;
CREATE DATABASE IF NOT EXISTS orbit;
DELIMITER $$
CREATE PROCEDURE orbit.enable_consumers()
SQL SECURITY DEFINER
BEGIN
UPDATE performance_schema.setup_consumers SET ENABLED = 'YES'
WHERE NAME IN ('statements_digest', 'events_statements_current', 'events_waits_current', 'events_statements_cpu');
END $$
DELIMITER ;
GRANT EXECUTE ON PROCEDURE orbit.enable_consumers TO 'orbit_monitor'@'%';Troque change-me por uma senha gerada. A procedure roda com os direitos de quem a criou, então o
usuário de monitoramento liga os consumers sem ter UPDATE no performance_schema.
O usuário não precisa de PROCESS. Medido no MySQL 8.4.11: um usuário só com SELECT no
performance_schema vê as sessões de todos os usuários em threads, events_waits_current,
events_statements_current e data_lock_waits, e o mesmo resumo de digests, com as mesmas linhas
de um usuário que tem PROCESS. O PROCESS controla o SHOW PROCESSLIST e o
information_schema.PROCESSLIST, que o Orbit nunca lê.
Uma réplica de leitura recebe o usuário e a procedure pela replicação. Os consumers pertencem a
cada instância, e a procedure roda numa réplica com read_only e super_read_only ligados
(medido), então cadastre cada réplica que você quer acompanhar como uma conexão própria. No Aurora,
cadastre o endpoint da instância (<instance>.<id>.<region>.rds.amazonaws.com), não o do cluster:
o endpoint do cluster passa para outra instância num failover, e os blocos de CloudWatch do Deck
casam com o identificador da instância, o primeiro segmento do endpoint, então um endpoint de
cluster não mostra nenhum.
O MAX_USER_CONNECTIONS 5 cobre a conexão única do coletor e o momento em que uma verificação ou
um plano abre outra.
3. Ligando no Orbit
Os corpos de criação e de alteração de uma conexão aceitam monitor, e a visão de gestão o
devolve sem a senha:
{"monitor": {"enabled": true, "user": "orbit_monitor", "password": "change-me"}}userprecisa ser diferente douserda conexão. Numa alteração, uma senha ausente ou""mantém a guardada, e ummonitorausente mantém a configuração guardada.- A senha é selada com
ORBIT_SEAL_KEYcomo a do editor, e oGETresponde{"enabled": true, "user": "orbit_monitor", "hasPassword": true}. - Com
enabledligado, salvar também conecta como o usuário de monitoramento, e recusa com400 connection_failedquando isso falha. Host, porta, modo TLS e CA são os da conexão. - Uma mudança em
monitorentra na auditoria nos campos alterados dedatabase.updatecomomonitor.
Depois rode a verificação, POST /api/v1/databases/{id}/monitor/check (settings.manage). Ela
conecta como o usuário de monitoramento, chama orbit.enable_consumers() quando um consumer está
desligado, e responde em cada item o que fazer quando ele falha, com a correção escrita para RDS
for MySQL, Aurora MySQL ou MySQL operado por você:
| Verificação | Passa quando |
|---|---|
connect | O usuário de monitoramento consegue entrar |
performance_schema | @@performance_schema vale 1 |
consumer_statements_digest | O consumer statements_digest está ligado |
consumer_events_statements_current | O consumer events_statements_current está ligado |
consumer_events_waits_current | O consumer events_waits_current está ligado |
grant_select_performance_schema | O usuário lê events_statements_summary_by_digest e threads |
digest_length | max_digest_length, performance_schema_max_digest_length e performance_schema_max_sql_text_length valem 1024 ou mais |
Como o coletor roda
- Um coletor por conexão monitorada, dentro do
orbit-api(uma réplica, por projeto), numa conexão MySQL só dele ao schemaperformance_schema, com o TLS da conexão eMAX_EXECUTION_TIME3000 msna sessão. Cada consulta tem 5 s. - Ao conectar, lê a versão, o
@@performance_schemae seSUM_CPU_TIMEexiste, e chamaorbit.enable_consumers(); onde a procedure não existe a chamada falha e o coletor segue. - A cada 10 s lê o
setup_consumers, chamando a procedure de novo quando um consumer está desligado, e depois os digests do topo, deixando de fora as instruções cujo schema éperformance_schema, entre elas as do próprio coletor. A cada segundo lê as sessões ativas; comevents_waits_currentouevents_statements_currentdesligado, pula essa leitura em vez de contar toda sessão comoCPU. - Depois de uma falha fecha a conexão e abre outra 1 s depois, dobrando até 60 s; o
orbit_dbm_upfica em 0 nesse meio-tempo e oorbit_dbm_collect_errors_totalconta a etapa. Com operformance_schemadesligado ou faltando um grant, tenta de novo a cada 60 s. - Salvar a conexão reinicia o coletor dela numa conexão nova. Desligar o monitoramento ou apagar a conexão o para e remove as séries dela. Desligar o recurso Conexões de banco de dados, ou o Orbit SQL junto com ele, para todos os coletores e fecha as conexões deles; religar o recurso os inicia de novo.
GET /api/v1/databases/monitor dá o state de cada conexão: collecting; setup (conectado,
mas o performance_schema ou um consumer está desligado, ou falta um grant; o error diz qual);
down (sem conexão; o error diz por quê); ou off.
Chamadas por intervalo
O top SQL mostra as chamadas por segundo de cada instrução na janela e, ao lado, quantas vezes ela
rodou em cada intervalo inteiro: a média sobre os intervalos da janela, uma linha com cada um (do
mais antigo ao mais novo) e o intervalo mais movimentado. O seletor acima da tabela oferece os
intervalos que cabem de 2 a 240 vezes na janela da página, entre 1m, 5m, 15m e 1h, e começa
no primeiro que cabe 30 vezes ou menos: 1m para 15 minutos, 5m para uma hora, 15m para 6
horas, 1h para um dia ou mais. A escolha fica na URL como ?interval=.
- A contagem é
sum by (schema, digest) (increase(orbit_dbm_query_calls_total{db="<id>"}[<interval>]))com passo do intervalo, sobre intervalos inteiros: o fim da janela é arredondado para baixo até o intervalo, então o intervalo ainda em andamento fica de fora. Oincrease()extrapola até as bordas do intervalo e a página arredonda para a chamada: no engine, 4 chamadas a cada 15 s dão 16 por1m, 80 por5me 240 por15m, e 300 chamadas numa coleta caem no único intervalo de5mque as contém. - Um intervalo sem amostra (o digest estava fora dos
ORBIT_DBM_TOP_DIGESTSdo topo, ou o coletor estava fora) não tem contagem e fica fora da média; o contador do MySQL continuou contando, então o próximo intervalo com amostra traz essas chamadas. - Ordene por qualquer uma das colunas, ou agrupe a tabela por chamadas por intervalo: menos de 1, 1 a 9, 10 a 99, 100 a 999, 1.000 a 9.999 e 10.000 ou mais, o grupo mais movimentado primeiro, cada um mantendo a ordenação.
- As instruções do próprio provedor ficam de fora a não ser que a página as mostre, como em todo o resto dela.
Explain
POST /api/v1/databases/{id}/explain com {"digest": "...", "schema": "shop"} responde
{"plan": {...}, "sampleSeenMs": ...}, o plano como o EXPLAIN FORMAT=JSON o entrega.
- O usuário de monitoramento lê o
QUERY_SAMPLE_TEXTdo digest. Só um digestSELECTouWITHganha plano, e a amostra também precisa passar pelo gate de instruções do editor; umEXPLAIN ANALYZE, uma escrita, uma função bloqueada ou mais de uma instrução é400, e um digest sem amostra também. - O MySQL corta a amostra em
performance_schema_max_sql_text_lengthbytes (1024por padrão) e termina com.... Para caber o..., o MySQL tira um caractere partido no limite e mais três, então uma amostra com caracteres de 4 bytes termina até 12 bytes antes do limite (MySQL8.0.46e8.4.11). Uma amostra cortada é400 sample_truncated, com o limite na mensagem: suba para4096no grupo de parâmetros da instância (estático: reinicie a instância) ou nomy.cnf, e explique a próxima amostra que o MySQL guardar. - Toda recusa diz a causa em
error.code:monitor_off,not_explainable,no_sample,sample_truncated,sample_refused(o gate),explain_denied(erro1142do MySQL),explain_refused,explain_timeout,database_unreachable(502) ounot_found(404). O Deck descreve cada uma no idioma de quem lê. - O plano roda como o usuário do editor SQL, nunca o de monitoramento, numa conexão só dele, numa transação somente leitura com o schema do digest como padrão e limite de 10 s.
- Os literais entre aspas do plano viram
?, e os números também, nas condições dele. Uma recusa do MySQL volta só com o número do erro, porque a mensagem do MySQL pode citar a amostra. - Cada pedido entra na auditoria como
databases.explain, com o digest, o schema e o resultado.
Instruções com os valores
O top SQL mostra cada instrução normalizada, cada valor um ?. Um papel que também tem
databases.raw_sql (o admin tem; dê-a a um papel personalizado para um tech lead) ganha a ação
"Mostrar valores" na gaveta de uma instrução: as últimas execuções dela como o cliente as enviou, com
os valores, das mais novas para as mais antigas, uma linha por texto com quantas execuções o
trouxeram e o tempo da mais recente, e a execução mais lenta que a tabela de digests guardou
(QUERY_SAMPLE_TEXT).
- As execuções vêm do histórico de instruções do MySQL:
events_statements_history(as últimas 10 instruções de cada sessão, ligado por padrão),events_statements_history_long(as últimas 10.000 de todas as sessões, com o consumer ligado) eevents_statements_current, lidos pelo usuário de monitoramento, que já temSELECTnoperformance_schema. Ligue o histórico longo para ver mais que as últimas:performance-schema-consumer-events-statements-history-long = ONnomy.cnf, ouUPDATE performance_schema.setup_consumers SET ENABLED = 'YES' WHERE NAME = 'events_statements_history_long'(até o próximo restart; no RDS, inclua-o emorbit.enable_consumers()). - O MySQL guarda os primeiros
performance_schema_max_sql_text_lengthbytes de cada instrução (1024por padrão) e a resposta marca uma cortada. - Toda revelação, concedida ou recusada, fica na trilha de auditoria:
databases.revealcom o leitor, a conexão, o digest, o schema e quantas instruções voltaram, nunca uma instrução. Sem a permissão a rota responde403e a trilha tem umaccess.denied. - Os valores são lidos quando pedidos e respondidos a esse leitor: o Orbit não guarda nenhum, e
nenhum chega ao
/metrics, a uma linha de log ou a outro leitor. POST /api/v1/databases/{id}/reveal{digest, schema}exigedatabases.raw_sqledatabases.querynuma conexão que o papel alcança, com o monitoramento ligado (400 monitor_offcaso contrário); só MySQL, já que o PostgreSQL não é monitorado.
Traces e logs de uma instrução
O Orbit liga um digest aos spans que o executaram, como o Datadog liga o Database Monitoring ao APM.
O orbit-stack dá a cada span MySQL ou MariaDB com uma instrução (db.query.text ou db.statement,
vinda de um SDK ou do probe eBPF) mais um atributo, orbit.sql.signature: 16 dígitos hexadecimais
calculados da instrução como o MySQL 8 calcula o texto do digest. Os comentários, um traceparent
do sqlcommenter entre eles, saem, enquanto um hint do otimizador (/*+ ... */) fica e um comentário
versionado (/*!40001 ... */) é lido como SQL. Literais, variáveis de usuário e placeholders (?,
%s, %(name)s, :name) viram ?; uma lista IN ou uma sequência de linhas VALUES conta como
uma só, e LIMIT 20 e LIMIT 20, 20 ficam separados; palavras-chave e seus sinônimos ficam como o
MySQL as escreve. O orbit-api calcula a mesma assinatura de cada DIGEST_TEXT que guarda.
- Na gaveta de um digest, Traces que a executaram abre a lista de traces, raízes de fundo
incluídas, filtrada por
orbit.sql.signaturena mesma janela. Um trace abre os seus logs. - Na gaveta de um span, Monitoramento de bancos abre o digest de uma conexão monitorada com a
mesma assinatura, com a gaveta aberta em volta da hora do span. Se houver vários, o Orbit escolhe
primeiro o schema do span (
db.namespace), depois o seu servidor (server.address), depois o visto mais recentemente. - Quando o app acrescenta um comentário
traceparentdo sqlcommenter, Sessões ao vivo mostra um link Trace na instrução em execução. O orbit-api lê doSQL_TEXTsó os 32 dígitos hexadecimais do id do trace; a instrução e os seus literais ficam no MySQL. O MySQL guarda os primeirosperformance_schema_max_sql_text_lengthbytes (1.024 por padrão), então uma instrução longa perde um comentário no fim. GET /api/v1/databases/monitor?signature=<16 hex>lista, para cada conexão monitorada, os digests guardados com essa assinatura;GET /api/v1/databases/{id}/digestsresponde asignaturede cada digest. Um digest que não pode ligar (abaixo) temsignaturenula e trazsignatureCut, os bytes de tokens em que a assinatura para naquele servidor; a resposta do monitor o traz numa conexão em que um digest assim é a instrução do span.
A ligação precisa da mesma instrução nas duas pontas. Por padrão o MySQL calcula o hash e guarda os
primeiros 1.024 bytes de tokens de um digest (max_digest_length), e a assinatura para no mesmo
token, então um select longo de ORM ainda liga. Uma instrução que passa de 1.024 bytes assina
diferente da instrução que os seus primeiros tokens formam, então o span dela nunca abre o digest
de uma instrução mais curta. O orbit-api lê max_digest_length e
performance_schema_max_digest_length a cada conexão. Acima de 1.024, o MySQL dá digests próprios
a instruções que só diferem depois desse ponto: um digest cujo texto passa do corte fica sem
assinatura, e a gaveta dele e o span explicam o motivo. Com performance_schema_max_digest_length
abaixo de max_digest_length, o MySQL corta o texto antes do que entra no hash, e dois digests
podem mostrar o mesmo texto; ali um digest só liga enquanto o seu texto ocupa até 252 bytes de
tokens, porque o token seguinte, um alias de 256 caracteres, pode ocupar 772. No padrão, um texto
acima de 956 bytes conta como cortado: os traces dele são os das instruções cortadas ali, e a
instrução inteira que termina ali ainda o abre pelo span. O probe guarda o primeiro KiB de uma instrução, então uma instrução que ele cortou
antes do limite do MySQL também não liga, e um span de um banco que o Orbit não monitora não tem
digest para abrir. Sob ANSI_QUOTES, um identificador entre aspas duplas é lido como texto, e essa
instrução pode abrir outro digest. Contra o STATEMENT_DIGEST do próprio MySQL, nas duas linhas de
versão do MySQL 8 que o Orbit suporta, a assinatura ligou 1.424 de 1.424 instruções sintéticas, 394
de 394 instruções que o probe eBPF viu num app Laravel e 69 de 69 instruções de dez ORMs e drivers
sem nenhuma ligação errada, e 75 de 76 instruções mais difíceis de ORMs e drivers com uma ligação
errada, a do ANSI_QUOTES. No MySQL 8.0.46, um conjunto de 11 instruções, 8 delas longas, ligou
11 de 11 no padrão, e deu 4 e 3 ligações, todas certas, com os dois comprimentos em 4096 e com
max_digest_length em 4096 sobre performance_schema_max_digest_length em 1024, onde assinar
todo digest dava 25 ligações, 14 delas erradas. Um conjunto mais difícil, de 72, com aliases de 200
caracteres ASCII e de 60 caracteres CJK bem no corte e introdutores de charset, deu 64, 16 e 2
ligações nesses três servidores, nenhuma errada.
Um papel para um time de bancos
databases.query sozinha abre o monitoramento de bancos e o editor SQL nas conexões que um papel
alcança, e nada mais do console. Para dar só isso a um time:
- Administração → Papéis → Novo papel. Marque
databases.querye nada mais. - Em Conexões de banco de dados, marque as conexões que o time pode ver, ou nenhuma para todas.
- Dê esse papel aos usuários do time.
Eles caem em Bancos de dados depois do login, veem a frota, a carga de cada conexão, o top SQL, as sessões e os planos, e rodam SQL somente leitura nessas conexões pelo editor SQL. Orbit SQL, Explore, o parque e os dashboards continuam fechados, assim como toda conexão que o papel não lista.
Quem decide é o orbit-api, não o Deck: uma conexão fora da lista do papel responde 404 not_found
em toda rota sob /api/v1/databases e em POST /api/v1/sql/query e /explain, como uma fora dos
seus allowedRoles, e as rotas de lista a deixam de fora. Os allowedRoles da conexão e a lista do
papel valem juntos. Os gráficos do monitoramento leem GET /api/v1/databases/query_range, que exige
databases.query e recusa qualquer expressão cujas séries não sejam as orbit_dbm_* das conexões
alcançadas (presas por db) ou as aws_rds_* das suas instâncias RDS (presas por
dbinstance_identifier). telemetry.query lê toda série do engine, estas inclusive: um papel
restrito a algumas conexões não deve tê-la.
Um papel que lista conexões não concede alcance maior: um usuário cujo papel lista algumas não cria,
não edita nem concede um papel que alcance mais delas, ou todas (403, auditado como
access.denied com reason: "subset").
Rotas de monitoramento
| Rota | Requer | Resposta |
|---|---|---|
GET /api/v1/databases/monitor | databases.query, e os allowedRoles da conexão | {databases: [{id, name, engine, host, enabled, state, version, performanceSchema, lastCollectMs, error}]} |
GET /api/v1/databases/query_range?expr=&from=&to=&step= | databases.query; toda série presa a uma conexão alcançada | a resposta do query_range; 404 para uma conexão que o papel não alcança, 400 para qualquer outra série |
POST /api/v1/databases/{id}/monitor/check | settings.manage | {checks: [{id, ok, detail, fix}]} |
GET /api/v1/databases/{id}/digests?digest=<hex>&digest=... | databases.query, com permissão | {digests: [{digest, schema, text, firstSeenMs, lastSeenMs, statement, explainable}]}, no máximo 200 digests; sem nenhum, lista os 200 vistos por último |
GET /api/v1/databases/{id}/activity | databases.query, com permissão | {atMs, sessions: [{user, host, schema, command, state, wait, timeMs, digest, text, internal}]}; internal é true na sessão de uma conta do provedor |
POST /api/v1/databases/{id}/explain | databases.query, com permissão | {plan, sampleSeenMs} |
POST /api/v1/databases/{id}/reveal | databases.raw_sql e databases.query, com permissão | {statements: [{text, durationMs, runs, truncated}], sample: {text, durationMs, truncated, seenMs} or null, maxLength} |
Um papel fora dos allowedRoles de uma conexão, ou cuja lista deixa a conexão de fora, recebe 404 not_found de toda rota acima e não vê a conexão na lista. A demonstração pública não monitora nada: demo-shop é PostgreSQL e aparece
como off, e as outras rotas são 403 lá.