refinery
v2.8.4
Para obtener una lista detallada de solicitudes de extracción vinculadas fusionadas en cada versión, consulte ChangeLog.md. Para obtener información más legible sobre cambios recientes, consulte Release_Notes.md.
La refinería es un proxy de muestreo basado en la cola y opera a nivel de una traza completa. La refinería examina las trazas enteras y aplica de manera inteligente las decisiones de muestreo a cada traza. Estas decisiones determinan si deben mantener o eliminar los datos de trazas en los datos muestreados reenviados a HoneyComb.
Un modelo de muestreo basado en la cola le permite inspeccionar una traza completa a la vez y tomar la decisión de probar en función de su contenido. Por ejemplo, sus datos pueden tener una extensión raíz que contiene el código de estado HTTP para servir para una solicitud, y otro lapso que contiene información sobre si los datos se atendieron desde un caché. Usando la refinería, puede optar por mantener solo rastros que tenían un código de estado 500 y también se sirvieron desde un caché.
Apoyo de la refinería Varios tipos de muestreo de cola:
http.status_code , puede incluir en sus datos muestreados:2xx4xx5xxLa refinería le permite combinar todas las técnicas anteriores para lograr su comportamiento de muestreo deseado.
La refinería está diseñada para sentarse dentro de su infraestructura donde todas las huellas pueden alcanzarla. La refinería puede ejecutarse independientemente o implementarse en un clúster de dos o más procesos de refinería accesibles a través de un equilibrador de carga separado.
Los procesos de refinería deben poder comunicarse entre sí para concentrar trazas en servidores individuales.
Dentro de su aplicación (u otras fuentes de eventos de Honeycomb), configuraría el API Host para que sea http(s)://load-balancer/ . Todo lo demás sigue siendo el mismo, como la clave API, el nombre del conjunto de datos, etc. ya que todo lo que vive con el cliente de origen.
Cada instancia de refinería debe tener un mínimo de:
linux/amd64 o linux/arm64En muchos casos, la refinería solo necesita un nodo. Si experimenta un gran volumen de tráfico, es posible que deba escalar a varios nodos, y es probable que necesite una pequeña instancia de Redis para manejar la escala.
Recomendamos aumentar la cantidad de RAM y la cantidad de núcleos después de su configuración inicial. Se pueden usar RAM y CPU adicionales aumentando los valores de configuración; En particular, CacheCapacity es un valor de configuración importante. El sistema Stress Relief de Refinery proporciona una buena indicación de cuán dura está funcionando la refinería, y cuando se invoca, registra (como reason ) el nombre del valor de configuración de la refinería que debe aumentarse para reducir el estrés. Use nuestra documentación de escala y solución de problemas para obtener más información.
La refinería está disponible como una tabla de timón en el repositorio de timón de panal.
Puede instalar refinería con el siguiente comando, que usa el archivo de valores predeterminados:
helm repo add honeycomb https://honeycombio.github.io/helm-charts
helm install refinery honeycomb/refineryAlternativamente, proporcione su propio archivo de valores personalizados:
helm install refinery honeycomb/refinery --values /path/to/refinery-values.yaml donde /path/to/refinery-values.yaml es la ruta del archivo.
Cuando opera en un clúster, Refinery espera reunir todos los tramos en rastro en una sola instancia para que pueda tomar una decisión de rastreo. Dado que cada tramo llega de forma independiente, cada instancia de refinería debe poder comunicarse con todos sus pares para distribuir trazas a la instancia correcta.
Esta comunicación se puede administrar de dos maneras: a través de una lista explícita de pares en el archivo de configuración, o mediante el autorregistro a través de un caché de Redis compartido. Las instalaciones generalmente deben preferir usar Redis. Incluso en grandes instalaciones, la carga en el servidor Redis es bastante ligera, y cada instancia solo hace algunas solicitudes por minuto. Una sola instancia de Redis con CPU fraccional suele ser suficiente.
La configuración se controla mediante los dos archivos de configuración de Refinery, que generalmente se conoce como config.yaml para la configuración y rules.yaml generales.yaml para la configuración de muestreo. Estos archivos se pueden cargar desde un sistema de archivos accesible, o cargarse con una solicitud GET no autenticada de una URL.
Obtenga más información sobre config.yaml y todos los parámetros que controlan la operación de la refinería en nuestra documentación de configuración de refinería.
Obtenga más información sobre rules.yaml y la configuración de muestras en nuestra documentación de métodos de muestreo de muestreo de refinería.
Es válido para especificar más de una fuente de configuración. Por ejemplo, sería posible tener un archivo de configuración común, además de un archivo separado que contiene solo claves. En la línea de comando, especifique múltiples archivos repitiendo el conmutador de línea de comando. En las variables de entorno, separe múltiples ubicaciones de configuración con comas.
La refinería es una aplicación típica de línea de comandos de estilo Linux, y admite varios interruptores de línea de comandos.
refinery -h imprimirá un texto extendido que enumera todas las opciones de línea de comandos y variables de entorno compatibles.
La refinería admite las siguientes variables de entorno clave; Consulte la ayuda de la línea de comando o la documentación en línea para la lista completa. Los interruptores de línea de comandos tienen prioridad sobre la configuración del archivo, y las variables de entorno tienen prioridad sobre ambos.
| Variable de entorno | Campo de configuración |
|---|---|
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 tiene prioridad sobre REFINERY_HONEYCOMB_API_KEY para la configuración LegacyMetrics.APIKey .
Enviar datos a Honeycomb requiere adjuntar una clave API a la telemetría. Para facilitar la gestión de la telemetría, la refinería admite las opciones de configuración ReceiveKeys y SendKey , junto con AcceptOnlyListedKeys y SendKeyMode . En varias combinaciones, tienen mucho poder expresivo. Consulte la documentación de configuración para obtener detalles sobre cómo establecer estos parámetros.
Un comienzo rápido para escenarios específicos está a continuación:
SendKey en una clave de Honeycomb válidaSendKeyMode a allSendKey en una clave de Honeycomb válidaSendKeyMode en nonblankReceiveKeys en la lista de excepcionesSendKey en una clave de Honeycomb válidaSendKeyMode unlistedSendKey en una clave de Honeycomb válidaSendKeyMode a missingonlyReceiveKeysAcceptOnlyListedKeys de trueSendKey en una clave de Honeycomb válidaSendKeyMode en listedonlyAcceptOnlyListedKeys en falseReceiveKeys en las teclas que deben reemplazarseSendKey en una clave de Honeycomb válidaSendKeyMode en listedonly + Nota + + Cuando use Beelines con una clave API clásica para enviar datos a la refinería, asegúrese de que SendKey también sea una clave clásica, no una clave de entorno y servicio (E&S).
Al comenzar con la refinería o al actualizar las reglas de muestreo, puede ser útil verificar que las reglas funcionen como se esperaba antes de comenzar a dejar caer el tráfico. Para hacerlo, use el modo de ejecución seca en la refinería.
Habilite el modo de ejecución seca agregando DryRun = true en su archivo de configuración ( config.yaml ). Luego, use el generador de consultas en la interfaz de usuario de panal para ejecutar consultas para verificar sus resultados y verificar que las reglas funcionen según lo previsto.
Cuando se habilita el modo de ejecución seca, la métrica trace_send_kept se incrementará para cada traza, y la métrica para trace_send_dropped permanecerá 0 , lo que refleja que estamos enviando todas las trazas a panal.
La refinería utiliza colas limitadas y búferes circulares para administrar trazas de asignación, por lo que incluso bajo el uso de memoria de alto volumen no debería expandirse dramáticamente. Sin embargo, dado que las trazas se almacenan en un búfer circular, cuando el rendimiento de las trazas excede el tamaño del búfer, las cosas comenzarán a salir mal. Si tiene estadísticas configuradas, un contador llamado collect_cache_buffer_overrun se incrementará cada vez que esto suceda. Los síntomas de esto serán que las trazas dejarán de acumularse juntos, y en su lugar, los tramos que deberían ser parte de la misma traza se tratarán como dos trazas separadas. Todas las trazas continuarán siendo enviadas (y muestreadas), pero algunas decisiones de muestreo se tomarán en datos incompletos. El tamaño del búfer circular es una opción de configuración llamada CacheCapacity . Para elegir un buen valor, debe considerar el rendimiento de trazas (por ejemplo, trazas / segundo iniciado) y multiplicarlo por la duración máxima de un rastro (como 3 segundos), luego multiplíquelo por un tampón grande (tal vez 10x) . Esta estimación dará un buen espacio para la cabeza.
Determinar el número de máquinas necesarias en el clúster no es una ciencia exacta, y está mejor influenciada al observar los excesos de búfer. Pero para una heurística aproximada, cuente en una sola máquina que use aproximadamente 2 GB de memoria para manejar 5,000 eventos entrantes y rastrear 500 trazas de subseconds por segundo (para cada traza completa que dura menos de un segundo y un tamaño promedio de 10 tramos por traza) .
La refinería ofrece un mecanismo llamado Stress Relief que mejora la estabilidad bajo carga pesada. La métrica stress_level es una métrica sintética en una escala de 0 a 100 que se construye a partir de varias métricas de refinería relacionadas con los tamaños de cola y el uso de la memoria. En funcionamiento normal, su valor generalmente debe estar en los dígitos únicos. Durante las explosiones de alto tráfico, los niveles de estrés pueden aumentar y luego caer nuevamente a medida que cae el volumen. A medida que se acerca a 100, es cada vez más probable que la refinería comience a fallar y posiblemente se estrellen.
Stress Relief es un sistema que puede monitorear la métrica stress_level y la carga de desplazamiento cuando el estrés se convierte en un peligro para la estabilidad. Una vez que se alcanza el ActivationLevel , el modo Stress Relief se activa. En este estado. La refinería probará deterministamente cada tramo en función de TraceID sin tener que almacenar el resto de la traza o evaluar las condiciones de la regla. Stress Relief permanecerá activo hasta que el estrés caiga por debajo del DeactivationLevel especificado en la configuración.
La configuración de alivio del estrés es:
Mode : configuración para indicar cómo se usa Stress Relief . never indica que Stress Relief no se activará. monitor significa que Stress Relief se activará cuando el ActivationLevel y se desactive cuando se alcanza el. always significa que el modo Stress Relief se contratará continuamente. El modo always está destinado a usarse en situaciones de emergencia.ActivationLevel : cuando el nivel de estrés aumenta por encima de este umbral, la refinería activará Stress Relief .DeactivationLevel : cuando el nivel de estrés cae por debajo de este umbral, la refinería desactivará Stress Relief .SamplingRate : la velocidad a la que la refinería muestras mientras Stress Relief está activo. El stress_level es actualmente el mejor proxy para la carga general en la refinería. Incluso si Stress Relief no está activo, si stress_level con frecuencia es frecuentemente superior a 50, es un buen indicador de que la refinería necesita más recursos: más CPU, más memoria o más nodos. Por otro lado, si stress_level nunca entra en dos dígitos, es probable que la refinería sea sobreprovisionada.
La refinería emite una serie de métricas para dar alguna indicación sobre la salud del proceso. Estas métricas deben enviarse a Honeycomb, típicamente con telemetría abierta, y también pueden expuestos a Prometeo. Los interesantes para ver son:
[incoming|peer]_router_* : ¿Cuántos eventos (sin información de rastreo) vs. tramos (tener información de rastreo) se han aceptado y cuántos enviados a sus compañeros?collect_cache_buffer_overrun : esto debería seguir siendo cero; Un valor positivo indica la necesidad de crecer el tamaño del búfer de traza circular de la refinería (a través de la configuración de CacheCapacity ).process_uptime_seconds : registra el tiempo de actividad de cada proceso; Busque reinicios inesperados como una clave para las limitaciones de memoria. El nivel de registro predeterminado de warn es bastante tranquilo. El nivel debug emite demasiados datos para ser utilizados en la producción, pero contiene una excelente información en un entorno de preproducción, incluida la información de decisión de rastreo. info está en algún lugar. Establecer el nivel de registro para debug durante la configuración inicial ayudará a comprender lo que funciona y lo que no, pero cuando aumentan los volúmenes de tráfico, debe configurarse para warn o incluso error . Los registros pueden enviarse a Stdout o a HoneyComb.
La refinería valida su configuración en el inicio o cuando se vuelve a cargar una configuración, y emite diagnósticos para cualquier problema. En el inicio, se negará a comenzar; En la recarga, no cambiará la configuración existente.
Verifique la configuración cargada utilizando uno de los puntos finales /query desde la línea de comando en un servidor que puede acceder a un host de refinería.
Los puntos finales /query están protegidos y se pueden habilitar especificando QueryAuthToken en el archivo de configuración o especificando REFINERY_QUERY_AUTH_TOKEN en el entorno. Todas las solicitudes en cualquier punto final /query deben incluir el encabezado X-Honeycomb-Refinery-Query establecido en el valor del token especificado.
Para las configuraciones basadas en archivos (el único tipo compatible actualmente), el valor hash es idéntico al valor generado por el comando md5sum para el archivo de configuración dado.
Para todos estos comandos:
$REFINERY_HOST debe ser la URL de su refinería.$FORMAT puede ser uno de yaml , toml o json .$DATASET es el nombre del conjunto de datos que desea verificar.Para recuperar toda la configuración de reglas:
curl --include --get $REFINERY_HOST/query/allrules/$FORMAT --header "x-honeycomb-refinery-query: my-local-token"
Para recuperar el conjunto de reglas que utiliza la refinería para el conjunto de datos especificado, que se devolverá como un mapa del tipo de muestra en su conjunto de reglas:
curl --include --get $REFINERY_HOST/query/rules/$FORMAT/$DATASET --header "x-honeycomb-refinery-query: my-local-token"
Para recuperar información sobre las configuraciones actualmente en uso, incluida la marca de tiempo cuando la configuración se cargó por última vez:
curl --include --get $REFINERY_HOST/query/configmetadata --header "x-honeycomb-refinery-query: my-local-token"
La refinería puede enviar telemetría que incluye información que puede ayudar a depurar las decisiones de muestreo que se toman. Para habilitar, en el archivo de configuración, establezca AddRuleReasonToTrace en true . Esto hará que los rastros que se envían a HoneyComb incluyen un campo meta.refinery.reason , que contendrá un texto que indica qué regla se evaluó que provocó que la traza se incluyera.
La refinería aún no amortigua las secuencias de trazas o las decisiones de muestreo al disco. Cuando reinicie el proceso, todas las trazas en vuelo se enjuagarán (enviadas hacia arriba a Honeycomb), pero perderá el registro de decisiones de trazas pasadas. Cuando se inicie de nuevo, comenzará con una pizarra limpia.
Dentro de cada directorio, la interfaz que las exportaciones de dependencia se encuentran en el archivo con el mismo nombre que el directorio y luego (en su mayor parte) cada uno de los otros archivos son implementaciones alternativas de esa interfaz. Por ejemplo, en logger , /logger/logger.go contiene la definición de interfaz y logger/honeycomb.go contiene la implementación de la interfaz logger que enviará registros a HoneyComb.
main.go configura la aplicación y toma decisiones sobre qué versiones de implementaciones de dependencia usar (por ejemplo, qué registrador, qué muestreador, etc.) inicia todo y luego inicia App .
app/app.go es el principal punto de control. Cuando termina su función Start , el programa se apaga. Lanza dos Router que escuchan eventos entrantes.
route/route.go escucha en la red para el tráfico entrante. Hay dos enrutadores que se ejecutan y manejan diferentes tipos de tráfico entrante: eventos provenientes del mundo exterior (el enrutador incoming ) y los eventos provenientes de otro miembro del clúster de refinería (tráfico peer ). Una vez que obtiene un evento, decide a dónde debe ir a continuación: ¿Es esta solicitud entrante un evento (o lote de eventos), y de ser así, ¿tiene una identificación de rastreo? Todo lo que no es un evento o un evento que no tiene una identificación de rastreo se entrega inmediatamente a transmission para que se reenvíe a HoneyComb. Si se trata de un evento con una identificación de rastreo, el enrutador extrae la identificación de rastreo y luego usa el sharder para decidir qué miembro del clúster de refinería debe manejar esta traza. Si es un compañero, el evento se enviará a ese compañero. Si es nosotros, el evento se transformará en una representación interna y se entregará al collector para agrupar los traces.
collect/collect.go El coleccionista es responsable de agrupar los tramos en trazas y decidir cuándo enviarlos a Honeycomb o si deben ser retirados. La primera vez que se ve una identificación de rastreo, el coleccionista comienza un temporizador. Si el tramo raíz, que es un tramo con una identificación de rastreo y sin ID de padre, llega antes de que expire el temporizador, entonces la traza se considera completa. Se envía el rastro y el temporizador se cancela. Si el temporizador caduca antes de que llegue el tramo raíz, el rastro se enviará si está completo o no. Justo antes de enviar, el coleccionista le pide al sampler una frecuencia de muestreo y si mantiene o no el rastro. El coleccionista obedece esta decisión de muestreo y la registra (el registro se aplica a cualquier tramo que pueda entrar como parte del rastro después de que se haya tomado la decisión). Después de tomar la decisión de muestreo, si se debe mantener el rastro, se transmite a la transmission para el envío real.
transmit/transmit.go es un envoltorio alrededor de las interacciones HTTP con la API de panal. Maneja los eventos por lotes juntos y los envía río arriba.
logger y metrics son para administrar los registros y las métricas que produce la refinería misma.
sampler contiene algoritmos para calcular las velocidades de muestra basadas en las trazas proporcionadas.
sharder determina qué par en una configuración de refinería agrupada se supone que maneja una traza individual.
types contienen algunas definiciones de tipo que se utilizan para entregar datos entre paquetes.
