refinery
v2.8.4
Para obter uma lista detalhada de solicitações de tração vinculadas mescladas em cada versão, consulte Changelog.md. Para obter informações mais legíveis sobre alterações recentes, consulte Release_Notes.md.
A refinaria é um proxy de amostragem baseado em cauda e opera no nível de um rastreamento inteiro. A refinaria examina traços inteiros e aplica de maneira inteligente decisões de amostragem a cada rastreamento. Essas decisões determinam se devem manter ou soltar os dados de rastreamento nos dados amostrados encaminhados ao favo de mel.
Um modelo de amostragem baseado em cauda permite inspecionar um rastreamento inteiro ao mesmo tempo e tomar uma decisão de amostrar com base em seu conteúdo. Por exemplo, seus dados podem ter uma extensão raiz que contém o código de status HTTP para servir para uma solicitação e outra extensão que contém informações sobre se os dados foram servidos a partir de um cache. Usando a refinaria, você pode optar por manter apenas traços que tinham um código de status 500 e também foram servidos a partir de um cache.
Refinaria apoia vários tipos de amostragem de cauda:
http.status_code , você pode incluir em seus dados amostrados:2xx4xx5xxA refinaria permite combinar todas as técnicas acima para alcançar o comportamento de amostragem desejado.
A refinaria foi projetada para sentar -se dentro da sua infraestrutura, onde todos os traços podem alcançá -lo. A refinaria pode executar independente ou ser implantada em um cluster de dois ou mais processos de refinaria acessíveis por meio de um balanceador de carga separado.
Os processos de refinaria devem ser capazes de se comunicar para concentrar traços em servidores únicos.
Dentro do seu aplicativo (ou outras fontes de eventos do favo de mel), você configuraria o API Host para ser http(s)://load-balancer/ . Tudo o resto permanece o mesmo, como chave da API, nome do conjunto de dados, e assim por diante, já que tudo isso vive com o cliente originário.
Toda instância de refinaria deve ter um mínimo de:
linux/amd64 ou linux/arm64Em muitos casos, a refinaria precisa apenas de um nó. Se estiver com um grande volume de tráfego, pode ser necessário escalar para vários nós e provavelmente precisar de uma pequena instância do Redis para lidar com a escala.
Recomendamos aumentar a quantidade de RAM e o número de núcleos após a configuração inicial. RAM adicional e CPU podem ser usadas aumentando os valores de configuração; Em particular, CacheCapacity é um importante valor de configuração. O sistema Stress Relief da refinaria fornece uma boa indicação de como a refinaria está funcionando duro e, quando invocados, logs (como reason ) o nome do valor da configuração da refinaria que deve ser aumentado para reduzir o estresse. Use nossa documentação de escala e solução de problemas para saber mais.
A refinaria está disponível como um gráfico de comando no repositório de compensação do favo de mel.
Você pode instalar a refinaria com o seguinte comando, que usa o arquivo de valores padrão:
helm repo add honeycomb https://honeycombio.github.io/helm-charts
helm install refinery honeycomb/refineryComo alternativa, forneça seu próprio arquivo de valores personalizados:
helm install refinery honeycomb/refinery --values /path/to/refinery-values.yaml Onde /path/to/refinery-values.yaml é o caminho do arquivo.
Ao operar em um cluster, a refinaria espera reunir todos os vãos em um rastreamento em uma única instância, para que possa tomar uma decisão de rastreamento. Como cada período chega de forma independente, cada instância da refinaria precisa ser capaz de se comunicar com todos os seus pares para distribuir traços para a instância correta.
Essa comunicação pode ser gerenciada de duas maneiras: através de uma lista explícita de pares no arquivo de configuração ou usando a auto-registro por meio de um cache Redis compartilhado. As instalações geralmente devem preferir usar o Redis. Mesmo em grandes instalações, a carga no servidor Redis é bastante leve, com cada instância fazendo apenas algumas solicitações por minuto. Uma única instância Redis com CPU fracionária é geralmente suficiente.
A configuração é controlada pelos dois arquivos de configuração da refinaria, que geralmente são chamados de configuração de configuração e rules.yaml config.yaml configuração de amostragem. Esses arquivos podem ser carregados de um sistema de arquivos acessíveis ou carregados com uma solicitação GET não autenticada de um URL.
Saiba mais sobre config.yaml e todos os parâmetros que controlam a operação da Refinaria em nossa documentação de configuração de refinaria.
Saiba mais sobre rules.yaml .
É válido especificar mais de uma fonte de configuração. Por exemplo, seria possível ter um arquivo de configuração comum, além de um arquivo separado que contém apenas teclas. Na linha de comando, especifique vários arquivos repetindo a chave de linha de comando. Nas variáveis de ambiente, separe vários locais de configuração com vírgulas.
A refinaria é um aplicativo típico de linha de comando no estilo Linux e suporta vários comutadores de linha de comando.
refinery -h imprimirá um texto de ajuda estendido listando todas as opções de linha de comando e variáveis de ambiente suportadas.
A refinaria suporta as seguintes variáveis de ambiente -chave; Consulte a ajuda da linha de comando ou a documentação on -line para a lista completa. Os interruptores de linha de comando têm precedência sobre a configuração do arquivo, e as variáveis de ambiente têm precedência sobre os dois.
| Variável de ambiente | Campo de configuração |
|---|---|
REFINERY_GRPC_LISTEN_ADDRESS | GRPCListenAddr |
REFINERY_REDIS_HOST | PeerManagement.RedisHost |
REFINERY_REDIS_USERNAME | PeerManagement.RedisUsername |
REFINERY_REDIS_PASSWORD | PeerManagement.RedisPassword |
REFINERY_HONEYCOMB_API_KEY | HoneycombLogger.LoggerAPIKey |
REFINERY_HONEYCOMB_METRICS_API_KEY | LegacyMetrics.APIKey |
REFINERY_HONEYCOMB_API_KEY | LegacyMetrics.APIKey |
REFINERY_QUERY_AUTH_TOKEN | QueryAuthToken |
NOTA: REFINERY_HONEYCOMB_METRICS_API_KEY tem precedência sobre REFINERY_HONEYCOMB_API_KEY para a configuração LegacyMetrics.APIKey .
O envio de dados ao Honeycomb requer anexar uma chave da API à telemetria. Para facilitar o gerenciamento da telemetria, o suporte da refinaria das opções de configuração ReceiveKeys e SendKey , juntamente com AcceptOnlyListedKeys e SendKeyMode . Em várias combinações, eles têm muito poder expressivo. Consulte a documentação de configuração para obter detalhes sobre como definir esses parâmetros.
Um início rápido para cenários específicos está abaixo:
SendKey para uma chave de favo de mel válidaSendKeyMode para allSendKey para uma chave de favo de mel válidaSendKeyMode como nonblankReceiveKeys para a lista de exceçõesSendKey para uma chave de favo de mel válidaSendKeyMode como unlistedSendKey para uma chave de favo de mel válidaSendKeyMode para missingonlyReceiveKeysAcceptOnlyListedKeys para trueSendKey para uma chave de favo de mel válidaSendKeyMode como listedonlyAcceptOnlyListedKeys para falseReceiveKeys para as chaves que devem ser substituídasSendKey para uma chave de favo de mel válidaSendKeyMode como listedonly + Nota + + Ao usar linhas de bolhas com uma chave de API clássica para enviar dados para a refinaria, verifique se o SendKey também é uma chave clássica, não uma chave de ambiente e serviço (E&S).
Ao começar com a refinaria ou ao atualizar as regras de amostragem, pode ser útil verificar se as regras estão funcionando conforme o esperado antes de começar a retirar o tráfego. Para fazer isso, use o modo de execução a seco na refinaria.
Ative o modo de execução a seco adicionando DryRun = true no seu arquivo de configuração ( config.yaml ). Em seguida, use o Consulta Builder na interface do favo de mel para executar consultas para verificar seus resultados e verificar se as regras estão funcionando conforme o pretendido.
Quando o modo de execução a seco estiver ativado, o métrico trace_send_kept incrementará para cada rastreamento, e a métrica para trace_send_dropped permanecerá 0 , refletindo que estamos enviando todos os traços para o favo de mel.
A refinaria usa filas limitadas e tampões circulares para gerenciar rastreios de alocação, portanto, mesmo sob uso de memória de alto volume, não deve expandir drasticamente. No entanto, dado que os traços são armazenados em um tampão circular, quando a taxa de transferência de traços excede o tamanho do buffer, as coisas começarão a dar errado. Se você tiver estatísticas configuradas, um contador denominado collect_cache_buffer_overrun será incrementado cada vez que isso acontecer. Os sintomas disso serão que os traços deixarão de ser acumulado juntos e, em vez disso, vãos que devem fazer parte do mesmo traço serão tratados como dois traços separados. Todos os traços continuarão sendo enviados (e amostrados), mas algumas decisões de amostragem serão tomadas em dados incompletos. O tamanho do tampão circular é uma opção de configuração chamada CacheCapacity . Para escolher um bom valor, considere a taxa de transferência de traços (por exemplo, traços / segundos iniciados) e multiplique isso pela duração máxima de um traço (como 3 segundos), multiplique isso por algum buffer grande (talvez 10x) . Esta estimativa dará um bom espaço.
Determinar o número de máquinas necessárias no cluster não é uma ciência exata e é melhor influenciada, observando os excedentes de buffer. Mas, para uma heurística grosseira, conte com uma única máquina usando cerca de 2 GB de memória para lidar com 5.000 eventos de entrada e rastrear 500 traços de subsegundos por segundo (para cada rastreamento completo que dura menos de um segundo e um tamanho médio de 10 vãos por rastreamento) .
A refinaria oferece um mecanismo chamado Stress Relief que melhora a estabilidade sob carga pesada. A métrica stress_level é uma métrica sintética em uma escala de 0 a 100 que é construída a partir de várias métricas de refinaria relacionadas a tamanhos de fila e uso de memória. Em operação normal, seu valor geralmente deve estar nos dígitos únicos. Durante as explosões de tráfego alto, os níveis de estresse podem subir e depois cair novamente à medida que o volume cai. À medida que se aproxima de 100, é cada vez mais provável que a refinaria comece a falhar e possivelmente travar.
Stress Relief é um sistema que pode monitorar a métrica stress_level e derramar carga quando o estresse se torna um perigo para a estabilidade. Quando o ActivationLevel for atingido, o modo Stress Relief se tornará ativo. Neste estado. A refinaria amostrará deterministicamente cada extensão com base no TraceID sem precisar armazenar o restante do rastreamento ou avaliar as condições das regras. Stress Relief permanecerá ativo até que o estresse caia abaixo do DeactivationLevel especificado na configuração.
As configurações de alívio do estresse são:
Mode - Configuração para indicar como Stress Relief é usado. never indica que Stress Relief não será ativado. monitor significa que Stress Relief será ativado quando o ActivationLevel e o desativar quando for atingido. always significa que o modo Stress Relief será continuamente envolvido. O modo always destina -se ao uso em situações de emergência.ActivationLevel - Quando o nível de tensão sobe acima desse limite, a refinaria ativará Stress Relief .DeactivationLevel - Quando o nível de estresse cair abaixo desse limiar, a refinaria desativará Stress Relief .SamplingRate - a taxa na qual as amostras de refinaria enquanto Stress Relief é ativo. Atualmente, o stress_level é o melhor proxy para a carga geral na refinaria. Mesmo que Stress Relief não esteja ativo, se stress_level estiver frequentemente acima de 50, é um bom indicador de que a refinaria precisa de mais recursos - mais CPUs, mais memória ou mais nós. Por outro lado, se stress_level nunca entrar em dois dígitos, é provável que a refinaria seja supervisionada.
A refinaria emite várias métricas para dar alguma indicação sobre a saúde do processo. Essas métricas devem ser enviadas ao favo de mel, geralmente com telemetria aberta, e também podem ser expostas a Prometeu. Os interessantes de assistir são:
[incoming|peer]_router_* : Quantos eventos (sem informações de rastreamento) vs. vãos (informações de rastreamento) foram aceitas e quantos enviados aos pares?collect_cache_buffer_overrun : Isso deve permanecer zero; Um valor positivo indica a necessidade de aumentar o tamanho do tampão de rastreamento circular da refinaria (via CacheCapacity de configuração).process_uptime_seconds : registra o tempo de atividade de cada processo; Procure reinicializações inesperadas como uma chave para restrições de memória. O nível padrão de registro de warn é bastante silencioso. O nível debug emite dados demais para serem usados na produção, mas contém excelentes informações em um ambiente de pré-produção, incluindo informações de decisão de rastreamento. info está em algum lugar entre. Definir o nível de registro para debug durante a configuração inicial ajudará a entender o que está funcionando e o que não é, mas quando o volume de tráfego aumentará, deve ser definido como warn ou mesmo error . Os logs podem ser enviados para stdout ou favo de mel.
A refinaria valida sua configuração na inicialização ou quando uma configuração é recarregada e emite diagnósticos para quaisquer problemas. Na startup, ele se recusará a começar; Na recarga, ele não alterará a configuração existente.
Verifique a configuração carregada usando um dos pontos de extremidade /query da linha de comando em um servidor que pode acessar um host de refinaria.
Os pontos de extremidade /query estão protegidos e podem ser ativados especificando QueryAuthToken no arquivo de configuração ou especificando REFINERY_QUERY_AUTH_TOKEN no ambiente. Todas as solicitações para qualquer endpoint /query devem incluir o cabeçalho X-Honeycomb-Refinery-Query definido no valor do token especificado.
Para configurações baseadas em arquivo (o único tipo atualmente suportado), o valor hash é idêntico ao valor gerado pelo comando md5sum para o arquivo de configuração fornecido.
Para todos esses comandos:
$REFINERY_HOST deve ser o URL da sua refinaria.$FORMAT pode ser um de yaml , toml ou json .$DATASET é o nome do conjunto de dados que você deseja verificar.Para recuperar toda a configuração de regras:
curl --include --get $REFINERY_HOST/query/allrules/$FORMAT --header "x-honeycomb-refinery-query: my-local-token"
Para recuperar o conjunto de regras que a refinaria usa para o conjunto de dados especificado, que será retornado como um mapa do tipo de amostrador ao seu conjunto de regras:
curl --include --get $REFINERY_HOST/query/rules/$FORMAT/$DATASET --header "x-honeycomb-refinery-query: my-local-token"
Para recuperar informações sobre as configurações atualmente em uso, incluindo o registro de data e hora quando a configuração foi carregada pela última vez:
curl --include --get $REFINERY_HOST/query/configmetadata --header "x-honeycomb-refinery-query: my-local-token"
A refinaria pode enviar telemetria que inclua informações que podem ajudar a depurar as decisões de amostragem que são tomadas. Para ativar, no arquivo de configuração, defina AddRuleReasonToTrace como true . Isso causará traços enviados ao favo de mel para incluir uma meta.refinery.reason , que conterá texto indicando qual regra foi avaliada que fez com que o rastreamento fosse incluído.
A refinaria ainda não buffer rastreios ou decisões de amostragem no disco. Ao reiniciar o processo, todos os traços de voo serão lavados (enviados a montante para o favo de mel), mas você perderá o registro de decisões de rastreamento anteriores. Quando iniciado, ele começará com uma lousa limpa.
Dentro de cada diretório, a interface as exportações de dependência está no arquivo com o mesmo nome do diretório e, em seguida, (na maioria das vezes) cada um dos outros arquivos são implementações alternativas dessa interface. Por exemplo, em logger , /logger/logger.go contém a definição da interface e logger/honeycomb.go contém a implementação da interface logger que enviará logs para o Honeycomb.
main.go configura o aplicativo e faz escolhas sobre quais versões das implementações de dependência usar (por exemplo, qual logger, qual amostrador etc.) inicia tudo e inicia App .
app/app.go é o principal ponto de controle. Quando sua função Start termina, o programa é desligado. Ele lança dois Router que ouvem para eventos de entrada.
route/route.go ouve na rede para o tráfego recebido. Existem dois roteadores em execução e lidam com diferentes tipos de tráfego de entrada: eventos vindos do mundo exterior (o roteador incoming ) e eventos provenientes de outro membro do cluster de refinaria (tráfego peer ). Depois de obter um evento, decide para onde deve ir a seguir: esta solicitação de entrada é um evento (ou lote de eventos) e, em caso afirmativo, ele tem um ID de rastreamento? Tudo o que não é um evento ou um evento que não possui um ID de rastreamento é imediatamente entregue à transmission para ser encaminhado para o favo de mel. Se for um evento com um ID de rastreamento, o roteador extrai o ID do rastreamento e depois usa o sharder para decidir qual membro do cluster de refinaria deve lidar com esse rastreamento. Se for um colega, o evento será encaminhado para esse par. Se somos nós, o evento será transformado em uma representação interna e entregue ao collector para agrupar vãos em traços.
collect/collect.go Na primeira vez em que um ID de rastreamento é visto, o colecionador inicia um temporizador. Se a extensão da raiz, que é uma extensão com um identificador de rastreio e sem identificação pai, chegar antes de o timer expirar, o rastreamento será considerado completo. O rastreamento é enviado e o temporizador é cancelado. Se o timer expirar antes da chegada da extensão da raiz, o rastreamento será enviado, seja ou não completo. Pouco antes de enviar, o coletor pede uma taxa de amostragem ao sampler e se deve ou não manter o rastreamento. O colecionador obedece a essa decisão de amostragem e a registra (o registro é aplicado a qualquer vãos que possam entrar como parte do rastreamento após a decisão da decisão). Depois de tomar a decisão de amostragem, para que o rastreamento seja mantido, ele será repassado à transmission para o envio real.
transmit/transmit.go é um invólucro em torno das interações HTTP com a API Honeycomb. Ele lida com eventos em lote e enviando -os a montante.
logger e metrics são para gerenciar os logs e métricas que a própria refinaria produz.
sampler contém algoritmos para calcular as taxas de amostragem com base nos traços fornecidos.
sharder determina qual par em uma configuração de refinaria em cluster deve lidar com um rastreamento individual.
types contêm algumas definições de tipo que são usadas para entregar dados entre os pacotes.
