.png%3Falt%3Dmedia%26token%3Da5dfada4-1947-4d21-ac3f-2b58f9581a40)
.png%3Falt%3Dmedia%26token%3Da5dfada4-1947-4d21-ac3f-2b58f9581a40)
📖
Getting Started
Welcome to Rely.io, the internal developer portal designed to empower modern engineering teams. Rely provides you automated visibility into your portfolio of services and user journeys, all while tracking their health, quality, and operational maturity in real-time.
This guide is designed to jump-start your journey with Rely.io. Here you will:
- Learn about Rely's core concepts;
- Familiarize yourself with Rely's web UI and API;
- Experience the power of Rely as an internal developer platform.
By the end of it, you will know:
- How to create and manage services using both Rely's UI and API.
- How to set up integrations with existing tools and systems.
- How to map out your product's user journeys for enhanced monitoring.
- How to use Scorecards and Service Level Objectives (SLOs) for performance tracking.
- How to generate reports that provide actionable insights into service health and quality.
Let's get started!
Rely's Service Catalog is a centralized place to access important information about all services in your organization. Here you will soon be able to see and manage its:
- Ownership
- Health status
- Operations and responsibilities
- Deployments
- Documentation
- And more!
Let's get you started with a simple example: imagine your organization uses an extensive microservice architecture with a few simple services. Eventually you want to map your entire business and stack in Rely, but you might not know where to start. As a rule of thumb, the main API that serves your front-end is usually a good way to start. So let's do that!
From UI
From the API
Let's head to Rely and open the Product Catalog page. Right now you should see something like this, an empty page like the one displayed bellow asking you to create a new service. So go ahead and click on
New Service. 
After doing so, you will be will see a creation form like the one bellow. This is your chance to populate it with all the details that make your service unique. In keeping with our example, let's name our new service "API."
Labels are key-value pairs that help you sort, filter, and organize your services. For instance, for our API service, let's set the following labels:
- Cloud Provider: AWS
- Infrastructure Components: API Gateway
- Region: eu-west2
These labels provide context to other stakeholders looking at the service catalog, making it easier to understand where and how the service fits within the overall ecosystem.
Properties link directly to essential resources such as documentation, contact channels, or code repositories. Now, let's add some useful properties:
- Contacts: A link to the on-call Slack channel
- Repository: Direct link to its GitLab repo.
- Documentation: Link to a Notion page with debugging information and historical incidents.
- Custom Link: A Dashboard link for Cloudwatch logs in AWS.
These properties centralize all key resources, enabling quicker navigation and streamlined incident response.
After filling in these details, go ahead and click
Create Service. You'll automatically be directed to a new page, where all the information you've just entered will be available for the entire team to see and use.
You might be glad to know that Rely has a public GraphQL API. As a means of illustrating its usage let's create an API service.
We will use python since we only require a single package, requests which you can install by running:
python -m pip install requests
For the next part, you will need your organization's own
CLIENT_ID and CLIENT_SECRET. Currently, the access to the API is restricted. To acquire credentials for the Public API, kindly get in touch with our support team.
Learn more about our API's authentication process and functionalities here.To perform any action with Rely's API, you need to use your client id and client secret to generate an access token:
import requests
TOKEN_AUTH_URL = " https://auth.rely.io/oauth/token"
CLIENT_ID = ...
CLIENT_SECRET = ...
USER_API_KEY = ...
AUDIENCE = "https://public.rely.io/api"
data = {
"grant_type": "client_credentials",
"client_id": CLIENT_ID,
"client_secret": CLIENT_SECRET,
"audience": AUDIENCE,
"api_key": USER_API_KEY
}
response = requests.post(TOKEN_AUTH_URL, data=data)
access_token = response.json()["access_token"]
Now that you have an access token, you can use it for every interaction you make with Rely's API. With regards to our service, let's assign it relevant labels and properties.
Labels are key-value pairs that help you sort, filter, and organize your services. For instance, for our API service, let's set the following labels:
- Cloud Provider: AWS
- Infrastructure Components: API Gateway
- Region: eu-west2
These labels provide context to other stakeholders looking at the service catalog, making it easier to understand where and how the service fits within the overall ecosystem.
Properties link directly to essential resources such as documentation, contact channels, or code repositories. Now, let's add some useful properties:
- Contacts: A link to the on-call Slack channel
- Repository: Direct link to its GitLab repo.
- Documentation: Link to a Notion page with debugging information and historical incidents.
- Custom Link: A Dashboard link for Cloudwatch logs in AWS.
These properties centralize all key resources, enabling quicker navigation and streamlined incident response.
import requests
from pprint import pprint
ACCESS_TOKEN = ... # Paste here the access token you generate previously
USER_ID = ... # Paste here the id that's been provided to you by the support team when request
API_URL = "https://graphql.rely.io/v1/graphql"
def fetch_graphql(operations_doc, operation_name, variables, access_token):
result = requests.post(
url=API_URL,
json={
"query": operations_doc,
"variables": variables,
"operationName": operation_name
},
headers={
"Authorization": f"Bearer {access_token}"
}
)
return result.json()
def create_service(query, variables, access_token):
response = fetch_graphql(query, "ServiceCreate", variables, access_token)
if "errors" in response:
pprint(response["errors"])
else:
pprint(response["data"])
query = """
mutation ServiceCreate(
$name: String!
$description: String
$ownerId: Int!
$properties: [EntityPropertyInput!]!
$tags: [EntityTagInput!]!
) {
data: serviceCreate(
object: {
description: $description
name: $name
ownerId: $ownerId
properties: $properties
tags: $tags
}
) {
id
}
}
"""
variables = {
"variables": {
"name": "API 2",
"description": "A copy of the API service",
"ownerId": USER_ID,
"properties": [{
"category": "contact",
"subcategory": "slack",
"name": "On-Call Channel",
"value": "https://evilcorp.slack.com/archives/C05FT5E4JJU",
"type": "link"
}, {
"category": "repository",
"subcategory": "gitlab",
"name": "Repo",
"value": "https://gitlab.com/evilcorp/platform-api",
"type": "link"
}, {
"category": "documentation",
"subcategory": "other",
"name": "RunBook",
"value": "https://www.notion.so/evilcorp/Service-Run-Books-2ae39df6068d44138862efcf31006f33",
"type": "link"
}, {
"category": "custom-link",
"name": "Cloudwatch Logs",
"value": "https://eu-west-2.console.aws.amazon.com/cloudwatch/home?region=eu-west-2#logsV2:log-groups/log-group/$252Faws$252gateway$252Fplatform-api-prod-run",
"type": "link"
}],
"tags": [{
"key": "Cloud Provider",
"value": "AWS"
}, {
"key": "Infrastructure Components",
"value": "Api Gateway"
}, {
"key": "region",
"value": "eu-west-2"
}]
},
"operationName": "ServiceCreate"
}
if __name__ == "__main__":
create_service(query, variables, ACCESS_TOKEN)
Now that you've successfully set up your first service, "API", through both the UI and API, you might be wondering about the most efficient way to catalog all the other services running in your organization. Manually pulling information from different teams and collating relevant resources can be time-consuming, not to mention prone to inaccuracies.
That's where Automated Service Discovery comes into play. Rely.io enables this feature for specific data sources, allowing you to build your service catalog automatically. You can find a list of compatible data sources and how the discovery mechanism works in the linked documentation.
In this guide, we'll demonstrate how to set up Automated Service Discovery using a Datadog integration - the process is the exact same as for any other data source, the only thing that differs is the process of creating the integration . This will enable us to populate our service inventory effortlessly, making it easier for us to manage and monitor the various services.
Head over to the
Data Sources tab and pick the type of plugin you want to add, which in our case will be Datadog. As you can see in the image below, brief guidelines accompany each field to guide you. For more detailed information visit the plugin's respective documentation page.
Once you've obtained the necessary keys from Datadog, complete the form and submit it. The plugin becomes available instantaneously, unlocking two crucial capabilities:
- First, you can now leverage the Automated Service Discovery feature. This allows you to handpick services from your Datadog account to import into Rely. Moreover, these services are generated with links to pertinent Datadog dashboards.
- Second, you can now harness the Datadog metrics and traces to establish Service Level Objectives (SLOs) in Rely, providing a data-driven way to gauge the performance of your services and user experiences.
Return to the
Service Catalog page and click the Create Service button once more. This time, however, choose the From automated discovery option. Instead of the familiar form, you'll be presented with a list of services that have been automatically discovered. For the sake of this example, let's say the list includes five new services discovered via Datadog: Webapp, Database, Auth0, CloudFront, StreamingAPI
Select all these services and click on the
Create Services button. You will then be redirected to your newly expanded service catalog, offering a comprehensive view of your operational landscape.Now that you have a fleshed out inventory of services, it's time to put these individual pieces together to visualize the bigger picture—your entire product. Rely.io provides a feature to do this, known as the Product Catalog. The Product Catalog encompasses both the Service Catalog and the User Journey Catalog, serving as a unified view that ties your engineering components to user-facing features. It is now time we shift our attention into the other half of the picture, the User Journeys.
The concept of a User Journey involves a series of actions that a user takes to accomplish a specific goal within your product.
For example, on an e-commerce a very clear intention that a user might have is to order an item from the platform. In order to do this however there's a sequence of procedures that he needs to perform in order to achieve that intent. First he needs to add items to his cart. Than he'll need to press the "Proceed to checkout" button where he'll be redirected to a 3-step form. In each of these steps he'll need to fill inputs, press buttons, make choices and so on and so forward until he can finally execute the order. During this entire procedure the product needs to react to his actions successfully in order for the user to complete his order.
Let's modal a user journey of our own within Rely. Navigate to the
User Journey Catalog section within the Product Catalog. Click the Create User Journey button and give it a meaningful name, like "Product Browsing" - meaning the intent of navigating, searching and visualizing a feed of products.Similarly to the Service Catalog, here you are able to assign labels link resources about your User Journey, besides that you are also able to pick a business criticality level. Once you create this new entity, you will be redirected to the User Journey page. Let us now define the actions that a user takes within it. If you're a technical persona (e.g. Software Engineer, DevOps, etc.), it's important to try and abstract yourself from the technicalities under the hood and put your product manager hat on. Log onto your own product, go over the journey, what are the options presented to the user? What's the terminology that is presented to them?
- 1.
User Opens Catalog - 2.
User Opens Catalog Item - 3.
User Filters Catalog - 4.
User Adds Item to Cart
All of these user actions trigger technical procedures and operations which must succeed for the user to be able to fulfill its objectives. Monitoring the health of these operations is crucial for a business to measure and improve the user experience that it provides. And the creation of this map between the user and the tech is a very useful tool that many companies skip. Let's do that now!
Return to the Service Catalog. In our API example, a Service Operation corresponds to an API endpoint like
POST /users. Service Operations are the building blocks of your Product Catalog. They represent the specific responsibilities your service has, which makes them vital for monitoring and understanding the health of your individual services and the product as a whole.Navigate to the individual service page of the API we previously created. Locate and click on the
Add Service Operation button. Let's define some basic operations:- 1.
GET /product/{id} - 2.
GET /search/products - 3.
GET /feed
Navigate back to your User Journey Catalog and open the journey you had previously created. Expand all of user actions by clicking the arrow on top of the table: 
. You will now be able to map each of these actions to the service operations that we just created. Apply the following map:
User Opens Catalog => GET /feedUser Opens Catalog Item => GET /product/{id}User Filters Catalog => GET /search/products
You might than realize that not all actions are associated with endpoints, some might rely solely on front end functionality - like the action of adding an item to the cart. At that moment you can go back to the
Webapp service page and fill it accordingly with the following operations:- Load Feed Canvas
- Load Product Details Page
- Update Cart Cache
When you're done, your user journey catalog will look something like this:
We're starting to get somewhere! Now your product and engineering teams, have materialized how their boundary of responsibilities works and they can use it in alignment, planning and to monitor its overall quality.
Congratulations on setting up your service catalog and your first user journey. Your setup is starting to take shape, but the journey doesn't stop here. Now that you have a holistic view of your operational landscape, it's time to delve into more advanced functionalities like setting Service Level Objectives (SLOs) and generating reliability reports.
Consider enriching both your Service Catalog and your User Journey Catalog. Add more services and user journeys to create a comprehensive landscape of your operational and user experience facets. For the services and user journeys you've already created, consider adding more links, such as to documentation or Git repositories, and providing more detailed descriptions. This extra layer of information helps bridge the gap between what's happening under the hood (services) and how users interact with your product (user journeys). Learn how to properly configure Services and User Journeys here and here respectively.
Now that you have your services and user journeys in place, it's essential to establish metrics that matter. Service Level Objectives (SLOs) are a proactive way to monitor the health and reliability of your services and user journeys. Learn how you set-up your first SLO here.
Accountability and visibility are crucial in modern engineering teams. Rely's reliability insights page allows you to generate data-rich reports to share with stakeholders, be it your engineering peers, your product team or higher management. Learn how to set-up your first report here.
Last modified 20d ago