Pular para o conteúdo

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.0 ou mais recente, MariaDB 10.5 ou 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:

bash
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:

  1. O orbit-api confere a instrução antes de tocar no banco: exatamente uma instrução, cuja primeira palavra-chave é SELECT, WITH, EXPLAIN, SHOW, VALUES, TABLE, DESCRIBE ou DESC, 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 lock pg_*advisory* e o resto da lista do contrato). Uma leitura que trava linhas também é recusada: FOR UPDATE e FOR NO KEY UPDATE como escritas, FOR SHARE, FOR KEY SHARE e LOCK IN SHARE MODE porque 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_error e diz o que foi recusado.
  2. Cada consulta roda em uma transação somente leitura, desfeita logo depois.
  3. 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):

sql
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:

sql
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:

ModoO que faz
verify-fullO 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
requireCriptografado, sem verificar o certificado
disableTexto puro: a senha e cada resultado atravessam a rede sem criptografia

Amazon RDS e Aurora

  • verify-full funciona como está: o orbit-api traz o pacote global de CAs do RDS, então nenhuma CA é necessária.
  • O security group do banco precisa liberar o orbit-api na 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-api sair para onde ele precisa. Acrescente a faixa de endereços do banco, com a porta, em components.orbit-api.databases.egress:
yaml
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_schema do 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-api a 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-api no 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ão SELECT email AS contact també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:

  1. a submete ao mesmo filtro de instruções do editor SQL, e só a SELECT ou WITH, sem leitura com trava (FOR SHARE, LOCK IN SHARE MODE) e sem sleep, benchmark, pg_sleep, get_lock nem as funções de advisory lock;
  2. dá a ela um LIMIT de 200 linhas, ou mantém um menor, e recusa um OFFSET acima de 100.000 linhas;
  3. lê o plano com EXPLAIN FORMAT=JSON (MySQL) ou EXPLAIN (FORMAT JSON) (PostgreSQL), nunca ANALYZE, e o recusa com 400 plan_refused quando 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 é o reltuples da tabela, e uma varredura sem filtro sob um LIMIT pequeno conta as linhas que devolve;
  4. 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 pelo orbit-api depois 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çãop95 no MySQLp99 no MySQLp95 do próprio MySQLp95 no PostgreSQLO que os fluxos fizeram
Nada além da carga2,48 ms2,93 ms0,263 ms2,59 ms-
Perguntas típicas, pelas proteções2,58 ms (+4%)2,88 ms0,251 ms (-5%)2,25 ms (-13%)cada uma leu menos de 100.000 linhas; 360 respondidas no MySQL
O mesmo sem pausa2,31 ms (-7%)2,73 ms0,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ções2,22 ms (-11%)2,62 ms0,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

RotaRequerCorpo e resposta
GET /api/v1/databasesdatabases.query ou settings.manage{configured, databases}
POST /api/v1/databasessettings.manageA conexão e a sua password → 201 {database, test}
PUT /api/v1/databases/{id}settings.manageO mesmo corpo → {database, test}
DELETE /api/v1/databases/{id}settings.manage204
POST /api/v1/databases/{id}/testsettings.manage{ok, serverVersion, readOnly, elapsedMs} ou {ok, error}
GET /api/v1/databases/{id}/schemadatabases.query{tables, truncated}
POST /api/v1/sql/querydatabases.query{sql, limit, timeoutMs, database} → {columns, rows, stats}
POST /api/v1/sql/explaindatabases.query{sql, database} → {plan}
GET /api/v1/databases/nocturnedatabases.query ou settings.manage{databases: [{id, name, engine, enabled, maskColumns}]}
PUT /api/v1/databases/{id}/nocturnesettings.manage{enabled, maskColumns} → {id, enabled, maskColumns}
POST /api/v1/databases/{id}/nocturne/querydatabases.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 /metrics do orbit-api, que o orbit-agent já coleta como job="sreorbit", component="orbit-api" para o orbit-stack;
  • o texto que o MySQL normalizou para cada digest (DIGEST_TEXT, com cada literal trocado por ?), só na memória do orbit-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érieLabelsOrigem
orbit_dbm_updb1 enquanto a conexão do coletor responde, senão 0
orbit_dbm_performance_schemadb@@performance_schema
orbit_dbm_query_calls_totaldb, schema, digestCOUNT_STAR
orbit_dbm_query_seconds_totaldb, schema, digestSUM_TIMER_WAIT / 1e12
orbit_dbm_query_lock_seconds_totaldb, schema, digestSUM_LOCK_TIME / 1e12
orbit_dbm_query_cpu_seconds_totaldb, schema, digestSUM_CPU_TIME / 1e12, no 8.0.28 ou mais recente com o consumer events_statements_cpu ligado
orbit_dbm_query_errors_totaldb, schema, digestSUM_ERRORS
orbit_dbm_query_rows_sent_totaldb, schema, digestSUM_ROWS_SENT
orbit_dbm_query_rows_examined_totaldb, schema, digestSUM_ROWS_EXAMINED
orbit_dbm_query_rows_affected_totaldb, schema, digestSUM_ROWS_AFFECTED
orbit_dbm_query_no_index_totaldb, schema, digestSUM_NO_INDEX_USED
orbit_dbm_query_full_scans_totaldb, schema, digestSUM_SELECT_SCAN
orbit_dbm_query_tmp_disk_tables_totaldb, schema, digestSUM_CREATED_TMP_DISK_TABLES
orbit_dbm_active_seconds_totaldb, waitAmostras de 1 s: os segundos que cada sessão ativa passou, sob a sua espera
orbit_dbm_query_active_seconds_totaldb, schema, digestAs mesmas amostras, por digest de instrução
orbit_dbm_collect_errors_totaldb, stageEtapas que falharam: connect, consumers, digests, activity
orbit_dbm_sampled_seconds_totaldbSegundos que a amostragem de sessões de 1 s cobriu, os passos somados
orbit_dbm_digests_read_timestamp_secondsdbHora 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:

promql
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 rdsadmin em orbit_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 um SELECT de tabelas do performance_schema, do information_schema, do mysql ou do sys, ou de variáveis @@GLOBAL ou @@aurora_*, que não cite outro schema. Uma leitura de variável de sessão como SELECT @@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 @@GLOBAL e as views information_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çãoPor que nenhuma conta de cliente a roda
INSERT, REPLACE, UPDATE ou DELETE numa tabela mysql.rds_*, como o heartbeatA 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_binUma 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 LOGSExige 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_accessO 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":

promql
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 (o firstSeenMs do 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 um TRUNCATE da tabela de digests, o firstSeenMs passa 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 um firstSeenMs de 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:

waitQuando
row_lockA 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/handlerA última espera da sessão em events_waits_current ainda está em andamento.
CPUQualquer 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çãoMemória do containerContagem do performance_schema
performance_schema = OFF192 MiB0
Ligado, todo tamanho no padrão436 MiB (+244)224,5 MiB
Ligado, os quatro *_history_long_size em 0382 MiB (+189)183,9 MiB
Ligado, os três comprimentos em 4096570 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_schema desligado. 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_size em 0. Da db.t4g.medium para cima, os tamanhos padrão. Ponha os três comprimentos em 4096 só 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):

ConsultaA cadaOcioso10 sessões num lock de linhaTabela de digests cheia (9.999)
Sessões ativas1 s0,82 ms de média, 2,2 ms de máximo2,1 ms de média, 5,9 ms de máximo1,4 ms de média, 6,8 ms de máximo
Os 100 digests do topo10 s1,1 ms de média1,5 ms de média20 ms de média, 69 ms de máximo
setup_consumers10 s0,34 ms de média0,42 ms de média0,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âmetroValorQuando
performance_schema1Sempre
performance_schema_events_statements_history_long_size0db.t4g.small
performance_schema_events_waits_history_long_size0db.t4g.small
performance_schema_events_stages_history_long_size0db.t4g.small
performance_schema_events_transactions_history_long_size0db.t4g.small
max_digest_length, performance_schema_max_digest_length, performance_schema_max_sql_text_length4096Opcional, 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âmetroValor
performance_schema1
performance_schema_consumer_events_statements_current1
performance-schema-consumer-events-waits-currentON (grafado com hífens, valores ON e OFF)
performance_schema_consumer_statements_digest1
performance_schema_consumer_global_instrumentation1
performance_schema_consumer_thread_instrumentation1

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:

ini
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 = ON

2. O usuário de monitoramento

Como o usuário administrador (no RDS, o usuário master), no writer:

sql
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:

json
{"monitor": {"enabled": true, "user": "orbit_monitor", "password": "change-me"}}
  • user precisa ser diferente do user da conexão. Numa alteração, uma senha ausente ou "" mantém a guardada, e um monitor ausente mantém a configuração guardada.
  • A senha é selada com ORBIT_SEAL_KEY como a do editor, e o GET responde {"enabled": true, "user": "orbit_monitor", "hasPassword": true}.
  • Com enabled ligado, salvar também conecta como o usuário de monitoramento, e recusa com 400 connection_failed quando isso falha. Host, porta, modo TLS e CA são os da conexão.
  • Uma mudança em monitor entra na auditoria nos campos alterados de database.update como monitor.

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çãoPassa quando
connectO usuário de monitoramento consegue entrar
performance_schema@@performance_schema vale 1
consumer_statements_digestO consumer statements_digest está ligado
consumer_events_statements_currentO consumer events_statements_current está ligado
consumer_events_waits_currentO consumer events_waits_current está ligado
grant_select_performance_schemaO usuário lê events_statements_summary_by_digest e threads
digest_lengthmax_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 schema performance_schema, com o TLS da conexão e MAX_EXECUTION_TIME 3000 ms na sessão. Cada consulta tem 5 s.
  • Ao conectar, lê a versão, o @@performance_schema e se SUM_CPU_TIME existe, e chama orbit.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; com events_waits_current ou events_statements_current desligado, pula essa leitura em vez de contar toda sessão como CPU.
  • Depois de uma falha fecha a conexão e abre outra 1 s depois, dobrando até 60 s; o orbit_dbm_up fica em 0 nesse meio-tempo e o orbit_dbm_collect_errors_total conta a etapa. Com o performance_schema desligado 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. O increase() 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 por 1m, 80 por 5m e 240 por 15m, e 300 chamadas numa coleta caem no único intervalo de 5m que as contém.
  • Um intervalo sem amostra (o digest estava fora dos ORBIT_DBM_TOP_DIGESTS do 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_TEXT do digest. Só um digest SELECT ou WITH ganha plano, e a amostra também precisa passar pelo gate de instruções do editor; um EXPLAIN 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_length bytes (1024 por 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 (MySQL 8.0.46 e 8.4.11). Uma amostra cortada é 400 sample_truncated, com o limite na mensagem: suba para 4096 no grupo de parâmetros da instância (estático: reinicie a instância) ou no my.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 (erro 1142 do MySQL), explain_refused, explain_timeout, database_unreachable (502) ou not_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) e events_statements_current, lidos pelo usuário de monitoramento, que já tem SELECT no performance_schema. Ligue o histórico longo para ver mais que as últimas: performance-schema-consumer-events-statements-history-long = ON no my.cnf, ou UPDATE performance_schema.setup_consumers SET ENABLED = 'YES' WHERE NAME = 'events_statements_history_long' (até o próximo restart; no RDS, inclua-o em orbit.enable_consumers()).
  • O MySQL guarda os primeiros performance_schema_max_sql_text_length bytes de cada instrução (1024 por padrão) e a resposta marca uma cortada.
  • Toda revelação, concedida ou recusada, fica na trilha de auditoria: databases.reveal com o leitor, a conexão, o digest, o schema e quantas instruções voltaram, nunca uma instrução. Sem a permissão a rota responde 403 e a trilha tem um access.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} exige databases.raw_sql e databases.query numa conexão que o papel alcança, com o monitoramento ligado (400 monitor_off caso 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.signature na 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 traceparent do sqlcommenter, Sessões ao vivo mostra um link Trace na instrução em execução. O orbit-api lê do SQL_TEXT só os 32 dígitos hexadecimais do id do trace; a instrução e os seus literais ficam no MySQL. O MySQL guarda os primeiros performance_schema_max_sql_text_length bytes (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}/digests responde a signature de cada digest. Um digest que não pode ligar (abaixo) tem signature nula e traz signatureCut, 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:

  1. Administração → Papéis → Novo papel. Marque databases.query e nada mais.
  2. Em Conexões de banco de dados, marque as conexões que o time pode ver, ou nenhuma para todas.
  3. 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

RotaRequerResposta
GET /api/v1/databases/monitordatabases.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çadaa 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/checksettings.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}/activitydatabases.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}/explaindatabases.query, com permissão{plan, sampleSeenMs}
POST /api/v1/databases/{id}/revealdatabases.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á.