Skip to main content

Getting Started

This guide will help you set up vizOps quickly and efficiently, enabling you to visualize your microservices architecture with minimal configuration. We'll cover the installation steps, configuration, and how to run the initial analysis to generate your first set of visualizations.

Note: As we continue the platform development, these are subject to change.

4.1 Installation and Setup​

Prerequisites​

Before you begin, ensure that you have the following prerequisites installed and configured on your system.

Supported Languages/Frameworks​

  • Backend Services: Java/Spring Boot, Javascript/Node.js
  • Frontend Clients: React

Note: Additional language support will be added in future releases.

System Requirements​

  • Java Development Kit (JDK): Version 8 or higher
  • Apache Maven: Version 3 or higher

Required Tools​

  • Git: For version control

Maven Dependency Installation​

To integrate vizOps into your Spring Boot project, follow these steps:

Step 1: Add the vizOps Agent Dependency​

Add the vizOps agent as a dependency in your pom.xml file. Place it within the <dependencies> section:

<!-- Add the vizOps agent as a dependency -->
<dependency>
    <groupId>io.vizops</groupId>
    <artifactId>vizops-agent</artifactId>
    <version>1.0.0</version>
</dependency>

Step 2: Save Changes​

Save the pom.xml file after adding the dependency.

Step 3: Verify the Dependency Installation​

Run the following command to verify that the dependency is correctly included in your build:

mvn clean install

Expected Output:

  • The build should complete successfully without errors.
  • You should see logs indicating that the vizOps agent has been added to your project.

If you encounter any issues, double-check the dependency entry in your pom.xml file for typos.

API Key Configuration​

To securely transmit metadata to the vizOps backend, you'll need to configure your API key.

Step 1: Obtain Your API Key​

  1. Sign Up: Visit vizOps.io and sign up for a free account.
  2. Access the Dashboard: Log in and navigate to your user dashboard.
  3. Generate API Key: In the API Keys section, click on Generate New API Key.
  4. Copy the Key: Your new API key will be displayed. Copy it for later use.

Step 2: Create Configuration File​

Create a configuration file named vizops-config.properties in the root directory of your project.

Example content of vizops-config.properties:

vizops.api.key=YOUR_API_KEY

Replace YOUR_API_KEY with the API key you obtained from the vizOps website.

Initial Agent Setup​

With the dependency and API key configured, you're ready to run the vizOps agent.

Step 1: Run the Agent​

Execute the following command in your project's root directory:

mvn vizops:analyze

Step 2: Monitor the Analysis​

The agent will:

  • Scan your project: Identify services, API contracts, and dependencies.
  • Extract metadata: Gather information necessary for visualization.
  • Transmit data: Securely send metadata to the vizOps backend.

Expected Output:

[INFO] --- vizops-agent:1.0.0:analyze (default-cli) @ your-project ---
[INFO] Starting vizOps analysis...
[INFO] Scanning source code...
[INFO] Services detected: 5
[INFO] Dependencies identified: 12
[INFO] Transmitting metadata to vizOps backend...
[INFO] Analysis complete.
[INFO] Visit your dashboard at https://vizops.io/dashboard to view the visualizations.

Step 3: Verify Successful Transmission​

  • Ensure that there are no error messages during the analysis.
  • Confirm that the number of services and dependencies detected matches your expectations.

4.2 Configuration (Minimal Approach)​

The vizOps agent is designed to work with minimal configuration, allowing you to focus on your development.

API Key Configuration File​

Location and Naming​

  • File Name: vizops-config.properties
  • Location: Root directory of your project.

File Content​

Add your API key to the configuration file:

vizops.api.key=YOUR_API_KEY

Note: Ensure that there are no extra spaces or hidden characters in the file.

How the API Key is Used​

  • Authentication: Validates your project with the vizOps backend.
  • Secure Transmission: Ensures that metadata is securely associated with your account.

Troubleshooting​

Invalid API Key Error​

  • Cause: Incorrect API key in the configuration file.
  • Solution:
    • Verify that you've correctly copied your API key.
    • Ensure there are no typos or extra spaces.
    • Regenerate the API key from the vizOps dashboard if necessary.

Missing Configuration File Error​

  • Cause: vizops-config.properties file is missing or incorrectly placed.
  • Solution:
    • Confirm that the file exists in the root directory of your project.
    • Check the file name for typos.

4.3 Initial Run and First Visualizations​

Now that vizOps is installed and configured, let's run the agent and explore the generated visualizations.

Running the Agent Locally​

Execute the following command:

mvn vizops:analyze

What Happens Next:

  • The agent scans your project and extracts architectural metadata.
  • Metadata is securely transmitted to the vizOps backend.
  • Visualizations are generated based on the collected data.

Viewing Visualizations​

Step 1: Access the vizOps Dashboard​

Step 2: Select Your Project​

  • If you have multiple projects, select the one you just analyzed from the project list.

Step 3: Explore the Initial Overview​

You will see an initial overview of the detected services and their interactions.

[[Insert placeholder for screenshot of the vizOps dashboard initial overview]]

Basic Dashboard Navigation​

Services Overview​

  • Location: Click on the Services tab.
  • Features:
    • Lists all detected microservices.
    • Displays key metrics such as the number of endpoints and dependencies.
  • Action: Click on a service name to view detailed information.

[[Insert placeholder for screenshot of the Services tab]]

Interpreting Initial Visuals​

Service Interactions​

  • Nodes: Represent individual services.
  • Arrows: Indicate the direction of dependencies or API calls.
  • Colors:
    • Green: Healthy services with no detected issues.
    • Yellow: Services with warnings.
    • Red: Services with critical issues.

Warnings and Errors​

  • Warning Symbols: Appear next to services or interactions with potential issues.
  • Details: Click or hover over the symbols to view error messages or warnings, such as:
    • Contract Mismatches: Inconsistencies between expected and actual API contracts.
    • Missing Dependencies: Services that call others which were not detected.
    • Circular Dependencies: Services that depend on each other, potentially causing tight coupling.

Troubleshooting​

No Services Detected​

  • Possible Causes:
    • Non-standard project structure.
    • Services not following naming conventions.
  • Solutions:
    • Ensure your project adheres to standard conventions for service directories and API definitions.
    • Verify that all services are properly annotated (e.g., @RestController in Spring Boot).

Incomplete Visualizations​

  • Possible Causes:
    • Incorrect API key.
    • Build process is skipping modules.
  • Solutions:
    • Confirm that the API key in vizops-config.properties is correct.
    • Check your Maven build settings to include all relevant modules.

Agent Errors During Analysis​

  • Possible Causes:
    • Incompatible versions of JDK or Maven.
  • Solutions:
    • Verify that you're using JDK 8+ and Maven 3+.
    • Update your tools if necessary.

General Guidelines​

  • Minimal Configuration: Remember that vizOps is designed to work out-of-the-box with minimal setup.
  • Automatic Service Discovery: The agent handles service discovery automatically, reducing manual configuration.
  • Stay Updated: Keep an eye on updates from vizOps for new features and language support.

Next Steps:

  • Explore advanced features in the dashboard, such as historical views and impact analysis.
  • Integrate vizOps into your CI/CD pipeline for continuous architectural validation (refer to the CI/CD Integration section in the documentation).

Feel free to reach out to the vizOps team if you have any questions or need assistance.

By following these detailed steps, you should now have vizOps installed, configured, and generating initial visualizations of your microservices architecture. Enjoy the enhanced visibility and insights that vizOps brings to your development workflow!