{"id":13805933,"url":"https://github.com/yammer/breakerbox","last_synced_at":"2025-05-13T21:31:49.121Z","repository":{"id":16151939,"uuid":"18897715","full_name":"yammer/breakerbox","owner":"yammer","description":"Frontend for Tenacity + Archaius","archived":false,"fork":false,"pushed_at":"2018-10-23T09:06:41.000Z","size":1892,"stargazers_count":63,"open_issues_count":5,"forks_count":29,"subscribers_count":29,"default_branch":"master","last_synced_at":"2024-11-18T22:31:00.431Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yammer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-18T00:23:29.000Z","updated_at":"2024-10-04T14:25:33.000Z","dependencies_parsed_at":"2022-08-04T08:00:25.633Z","dependency_job_id":null,"html_url":"https://github.com/yammer/breakerbox","commit_stats":null,"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yammer%2Fbreakerbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yammer%2Fbreakerbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yammer%2Fbreakerbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yammer%2Fbreakerbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yammer","download_url":"https://codeload.github.com/yammer/breakerbox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254031113,"owners_count":22002705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T01:01:06.403Z","updated_at":"2025-05-13T21:31:48.075Z","avatar_url":"https://github.com/yammer.png","language":"Java","funding_links":[],"categories":["Open Source"],"sub_categories":["Eclipse"],"readme":"Breakerbox [![Build Status](https://travis-ci.org/yammer/breakerbox.svg?style=flat-square)](https://travis-ci.org/yammer/breakerbox) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.yammer.breakerbox/breakerbox-service/badge.svg?style=flat-square)](https://maven-badges.herokuapp.com/maven-central/com.yammer.breakerbox/breakerbox-service)\n==========\n\nBreakerbox is a dashboard and dynamic configuration tool for [Tenacity](https://github.com/yammer/tenacity).\n\n![Breakerbox Dashboard](https://yammer.github.io/tenacity/breakerbox_latest.png)\n![Breakerbox Configure](https://yammer.github.io/tenacity/breakerbox_configure.png)\n\nRunning Breakerbox\n==================\n\n__Required:__ Breakerbox requires you to instrument your code with [Tenacity](https://github.com/yammer/tenacity) which is a library to aid\nin resilient design of foreign dependencies.\n\n[Download a release](https://github.com/yammer/breakerbox/releases) or build it yourself with [maven](https://github.com/yammer/breakerbox#building-breakerbox)\n\nExtract the archive and then run the following command\n\n```bash\njava -jar breakerbox-service-X.X.X.jar server breakerbox.yml\n```\n\nThen point your browser at ``http://localhost:8080``. You should see a dashboard\nconsisting of the local Breakerbox instance. By default it's backed by an in memory database, so\nany configuration changes you'll make won't be persisted anywhere until your configure it.\n\nConfiguring Breakerbox\n---------------------------------------\n\nHere's a very simple bare configuration of Breakerbox. Each section will be described in detail.\n\n```yaml\nbreakerbox:\n  urls: file:config.properties,http://localhost:8080/archaius/breakerbox\n  initialDelay: 0s\n  delay: 60s\n  \nbreakerboxHostAndPort: localhost:8080 #default\n\ndatabase:\n  driverClass: org.h2.Driver\n  url: jdbc:h2:mem:inMemory;DB_CLOSE_DELAY=-1\n  user: breakerbox\n  password: breakerboxpass\n  maxSize: 10\n  minSize: 2\n  checkConnectionWhileIdle: true\n  checkConnectionHealthWhenIdleFor: 1s\n\ntenacityClient:\n  connectionTimeout: 500ms\n  timeout: 1000ms\n\ndefaultDashboard: production\n\ninstanceDiscoveryClass: com.yammer.breakerbox.turbine.YamlInstanceDiscovery #default\n\nhystrixStreamSuffix: /tenacity/metrics.stream #default\n\nmetaClusters: \n  - production\n  - stage\n  - staging\n\nturbine:\n  urlSuffix: /tenacity/metrics.stream\n  clusters:\n    breakerbox:\n      instances:\n        - localhost:8080\n    production:\n      clusters:\n        - breakerbox\n\nrancherDiscovery:\n  serviceApiUrl: http://localhost:8080/v1/projects/1a5/services\n  parameters:\n    kind: 'service'\n  accessKey: 3E0F7DB0A2B601981F1B\n  secretKey: fWWKGNvmuWpSngyVYHXFMSnE5cDhZWKNkVmQS8zn\n\nmarathonDiscovery:\n  - marathonApiUrl: http://localhost:8080\n    marathonAppPort: 12345\n    marathonAppNameSpace: /exampleNameSpace\n    cluster: exampleCluster\n\nserver:\n  applicationConnectors:\n    - type: http\n      port: 8080\n  adminConnectors:\n    - type: http\n      port: 8081\n  gzip:\n    enabled: false\n  requestLog:\n    appenders:\n      - type: file\n        currentLogFilename: /var/log/breakerbox/requests.log\n        archivedLogFilenamePattern: /var/log/breakerbox/requests-%d.log\n        archivedFileCount: 5\n\nlogging:\n  level: INFO\n  appenders:\n    - type: file\n      currentLogFilename: /var/log/breakerbox/breakerbox.log\n      archivedLogFilenamePattern: /var/log/breakerbox/breakerbox-%d.log\n      archivedFileCount: 5\n```\n\nGzip Disabled\n-------------\nJavascript's EventSource doesn't support gzip encoded streams.\n\nPersistence Storage\n-------------------\n\nYou can choose between using an in-memory database (h2), Postgresql, MySQL (potentially other RDBMSes) and Azure Table.\n\nFor Postgresql simply modify the `database` section to (assumes the database \"breakerbox\" is created):\n\n```yaml\ndatabase:\n  driverClass: org.postgresql.Driver\n  url: jdbc:postgresql://localhost/breakerbox\n```\n\nFor MySQL:\n\n```yaml\ndatabase:\n  driverClass: com.mysql.jdbc.Driver\n  url: jdbc:mysql://localhost/breakerbox\n```\n\nIf you wish to use Azure Table remove the `database` section entirely and add\n\n```yaml\nazure:\n  accountName: your_test_account\n  accountKey: security_key\n  timeout: 2s\n  retryInterval: 500ms\n  retryAttempts: 1\n```\n\nIf you specify both `database` and `azure` it will only leverage the `database` store.\n\nAuthentication\n--------------\nBy default users that save configuration's will save it under the name `anonymous`.\n\nAt the moment it only supports authenticating users via LDAP and HTTP Basic-Auth which is configurable by adding:\n\n```yaml\nldap:\n  uri: ldaps://ldap.com\n  cachePolicy: maximumSize = 10000, expireAfterAccess = 15m\n  userFilter: ou=users,dc=company,dc=com\n  userNameAttribute: cn\n  connectTimeout: 500ms\n  readTimeout: 500ms\n```\n\nIf you need group membership filters you can see the additional documentation on [dropwizard-auth-ldap](https://github.com/yammer/dropwizard-auth-ldap)\n\nDashboard Configuration\n-----------------------------------------\n```yaml\nturbine: /path/to/instances.yml\n```\n\n```yaml\nurlSuffix: /tenacity/metrics.stream\nclusters:\nbreakerbox:\n  instances:\n    - localhost:8080\nproduction:\n  clusters:\n    - breakerbox\n```\n\n* `turbine` is a path to where a `yaml` configuration file containing the instances configuration is located (this is editable at runtime allowing for dynamic rediscovery).\n* `urlSuffix` defaults to `/tenacity/metrics.stream` you can alter this if you have this resource at a different location\n* `clusters` is the top level item for your clusters or dashboards you wish to have available. Underneath clusters you can specify dashboard names such as `breakerbox` or `production` in this example above. Underneath those you can specify either `instances` and `clusters`. `clusters` can reference other dashboards and will include their instances. This can reference cyclic dashboards and will add instances from both. `instances` lets you specify a single instance.  \n\nInstance Discovery Class\n------------------------\nSpecifies the `Java` canonical class name. It defaults to the `YamlInstanceDiscovery` implementation. You can also leverage the \n`com.yammer.breakerbox.turbine.KubernetesInstanceDiscovery` , `com.yammer.breakerbox.turbine.RancherInstanceDiscovery` , `com.yammer.breakerbox.turbine.MarathonInstanceDiscovery`and classes.\n\nTo integrate with RancherInstanceDiscovery, \n    \n    1. specify rancher services Api url, accessKey and secret key.\n        rancherDiscovery:\n            serviceApiUrl: http://localhost:8080/v1/projects/1a5/services\n            accessKey: 3E0F7DB0A2B601981F1B\n            secretKey: fWWKGNvmuWpSngyVYHXFMSnE5cDhZWKNkVmQS8zn\n        \n    2. add labels in rancher service containers:\n         a. tenacity.metrics.stream.enabled: true\n         b. tenacity.metrics.stream.port: 8080\n         c. service.cluster.name: clusterName\n    \n    3. Use hystrixStreamSuffix to provide custom path for hystrix metrics stream. It defaults to /tenacity/metrics.stream\n        \n    4. RancherInstanceDiscovery will create dashboards per service-cluster with service.cluster.name label and one aggregated production dashboard. Dashboards can be created, enabled, disabled by updating labels at runtime.\n\nTo integrate with MarathonInstanceDiscovery,\n    1. specify marathon services Api url, marathonAppPort(your application port), marathonAppNameSpace and clusterName.\n        marathonDiscovery:\n        - marathonApiUrl: http://localhost:8080\n          marathonAppPort: 12345\n          marathonAppNameSpace: /exampleNameSpace\n          cluster: exampleCluster\n\n    2. MarathonInstanceDiscovery will create dashboards per unique cluster specified in the config.  MarathonDiscovery supports multiple marathon namespaces and cluster support.\n\nMeta Clusters\n-------------\nThese are clusters that should be in the dashboard dropdown but aren't necessarily configurable. This is used for dashboards that are made up of multiple clusters that are informational, but don't make much context in the sense of configuring one of them.\n\n```yaml\nmetaClusters: \n  - production\n  - stage\n  - staging\n```\n\nAdding Breakerbox to your Dropwizard+Tenacity Service\n-----------------------\nIn any `Tenacity` service to have it poll `Breakerbox` for dynamic configurations add this to your service configuration.\n\n* `urls`: A comma-delimited list of breakerbox instances. The cluster you added in the `config.properties` is the identifier you want to supply here.\n* `initialDelay`: How long it should wait before the first poll.\n* `delay`: The interval at which to constantly check `Breakerbox` for configuration items. Here we specify every minute we'd like to check for new configurations.\n\n```yaml\nbreakerbox:\n  urls: http://breakerbox:8080/archaius/{the-cluster-you-setup-in-breakerbox}\n  initialDelay: 0s\n  delay: 60s\n```\n\nThere is a configuration hierarchy priority and it's good to understand it especially when using dynamic configurations.\n\n1. Breakerbox\n2. Service configuration YAML\n3. Tenacity defaults\n\nAdditional Configuration\n------------------------\nHere's a collection of things we have found very useful to make configurable.\n\n* `hystrixMetricsStreamServletMaxConnections`: The max number of connections any `Dropwizard+Tenacity` service will allow from Breakerbox.\n* `turbineHostRetry`: The interval at which to reconnect to a failed instance. 1s may be a bit fast as a default :)\n\n```yaml\narchaiusOverride:\n  turbineHostRetry: 1s\n  hystrixMetricsStreamServletMaxConnections: 5\n```\n\nThe client `Breakerbox` uses to fetch latest property keys and configurations is configurable by\n\n```yaml\ntenacityClient:\n  connectionTimeout: 500ms\n  timeout: 1000ms\n```\n\nBuilding Breakerbox\n-------------------\n\n`mvn clean package`\n\nThe artifact will then be available under `breakerbox-service/target`.\n\nRunning Tests\n-------------\n\n`mvn test`\n\nbreakerbox-azure doesn't have a mock for Azure Table as it wouldn't be that useful, so it requires a valid Azure Table account\nto run the tests. If you do not supply a valid Azure Table account, these tests will be ignored.\n\nDocker\n------\nJustin Plock created a [Docker for Breakerbox](https://registry.hub.docker.com/u/jplock/breakerbox/)\n\nBehind a Proxy\n--------------\nThe dashboard leverages Javascript's EventSource which doesn't support CORs. There is a configurable parameter `breakerboxHostAndPort`\nwhich defaults to `localhost:8080`. You can change this to allow for your proxy to direct traffic appropriately.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyammer%2Fbreakerbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyammer%2Fbreakerbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyammer%2Fbreakerbox/lists"}