Toggle methods and endpoints instantly
The Facet Java Agent uses the Bytecode Instrumentation API to dynamically enable and disable methods at runtime within your application. This is achieved by transferring control back to the caller of the method via injected return statements. After integration, you can toggle methods and endpoints in realtime without modifying or restarting you application.
Download the latest version of the Facet java-agent from the maven central.
-
Move the Facet java-agent JAR in the root of the application folder, or in a subfolder in your project.
-
Configure your JVM to load the agent during your application's premain start-up by passing this command-line argument:
-javaagent:/facet-agent-VERSION.jar. Replacefacet-ageent-VERSION.jarwith the absolute path of the Facet java-agent JAR. For IDEA users, this usually can be found at "Edit Configuration" -> "VM options". -
Create a
facet.ymlfile located in the same directory as thefacet-agent.jarfrom step 1.
apiKey: API_KEY
workspaceId: WORKSPACE_ID
name: APPLICATION_NAME
environment: ENVIRONMENT
In order to retrieve workspaceId and apiKey, you need to create an account in the Facet Dashboard
apiKey Used for Facet API authentication.
workspaceId The ID of the workspace.
name The name of your application.
environment The environment of your application deployment. For instance, you may use local for your local environment.
- Start your application and toggle endpoints and methods via the Facet Dashboard -> Applications.
- In case you've encountered some warnings/error, you can troubleshoot by opening the
facet.logfile, which is generated in the same directory with the facet.yml, once you start the application. Potential warnings and errors are logged in that file. - If you encounter
javax.management.InstanceAlreadyExistsExceptionwhile running locally, disable JMX integration in your IDE
- Endpoint management - disable or reroute endpoints on the fly for beta features or when application and performance issues arise.
- Chaos engineering - automated chaos engineering testing framework.
- Logging toggles - increase and decrease logging or add and remove log statements dynamically without deployment and restarting applications.
- Automatic documentation generation, as well as endpoint detection.
- Low code feature flags - low code alternative to traditional feature flag toggles.
We would love to hear your feedback!
Open an issue or send an email at engineering@facet.run.
Method toggles are achieved by stopping method execution and transferring control back to the caller via injected return statements called circuit breakers. Below are the default return values for method return types.
METHOD_RETURN_TYPE VALUE
------------------ -----------------------
byte Byte.MIN_VALUE
short Short.MIN_VALUE
int Integer.MIN_VALUE
long Long.MIN_VALUE
float Float.MIN_VALUE
double Double.MIN_VALUE
char Character.MIN_VALUE
boolean false
void void
other null
Circuit breakers are data driven and will soon be configurable. They are stored in this directory.
Frameworks are a combination circuit breakers which detect annotations, interfaces, and inheritance to customize the return value (response) creating support for HTTP requests and endpoints. If a framework is detected, the following return values will be used instead of the default circuit breaker mapping.
Currently, we support Spring Framework version 3.0.x and higher via the following spring annotations.
ANNOTATION_CLASS RETURN VALUE
(org.springframework.web.bind.annotation) (javax.servlet.http.HttpServletResponse)
----------------------------------------- -----------------
RequestMapping sendError(403,"Access Denied")
GetMapping sendError(403,"Access Denied")
PostMapping sendError(403,"Access Denied")
PutMapping sendError(403,"Access Denied")
DeleteMapping sendError(403,"Access Denied")
PatchMapping sendError(403,"Access Denied")
Frameworks are data driven and will soon be configurable.
Frameworks are stored in this directory.
A list of packages and classes not processed preventing method and endpoint toggle overload.
See block list.
Block lists are data driven and will soon be configurable.
Block lists are stored in this directory.
The future plans and high priority features and enhancements can be found in the GitHub project board.
Thank you for contributing to the project! Please read the CONTRIBUTING.md file to get started with the Facet Java-Agent project!
Java: JVM runtime 11 or higher is required, however, your source and target can be compiled to any java version.
View the demo here.