OpsLevel Logo
Product
Developer portal
Software catalog
The fastest path to total visibility
Standards
Your guide to safe, reliable software
Developer self-service
Empower developers to move faster, risk-free
Integrations
Connect your most powerful third-party tools
Use Cases
Ownership
Build accountability and clarity into your catalog
Standardization
Set and rollout best practices for your software
Developer Experience
Free up your team to focus on high-impact work
Customers
Resources
All Resources
Our full library of resources
Pricing
Flexible and designed for your unique needs
Podcast
Podcast
Conversations with technical leaders
Blog
Blog
DevOps resources, tips, and best practices
Demo
Demo
Videos of our product and features
Tech talk
Tech talk
Our POV on technical topics
Guide
Guide
Practical resources to roll out new programs and features
DocsLog In
Talk to usStart for free
No items found.
Share this
Table of contents
 
Resources
Guide

What you should track in your catalog

Product
Visibility
Tooling
Platform engineer
DevOps
Catalog
What you should track in your catalog
OpsLevel
|
January 24, 2023
What you should track in your catalog

Service catalogs show engineering teams what services actually exist and who owns them, making it easier for teammates to find information fast, which also means resolving problems faster—especially as you scale your team.

This article covers service cataloging basics for those just getting started.

What makes a good catalog?

A catalog, at its most basic, is the source of truth of all software services, who owns them, and what it takes to run them. In general, your catalog should be:

  • Complete - Rich with metadata, like: who owns it, a brief description, tech and API docs, categorization, related services, how to interact with it, SLAs, etc.
  • Current - Updated in real-time, so information is always accurate.
  • Automated - Updated with minimal human effort, with regular quality checks that flag priority issues.
  • Integrated - Plugged into daily workflows with little friction.‍
  • Searchable - Teammates can go from question to answer on their own.

What constitutes a service?

In practice, our customers rarely have clean-cut definitions for what a service actually is, and it varies from org to org. Sometimes cataloging needs extend beyond services to include components, like libraries, machine learning models, and storage buckets.

Our simple criteria to help you decide what goes into the catalog is a yes to any of these questions:

  1. Is a specific team or person responsible for it?
  2. Is it deployed on its own?
  3. Is it defined in another tool that integrates with OpsLevel? 

For anything you catalog, keep in mind that OpsLevel believes teams are owners, not individual people. Consider your use cases, as well (e.g. ownership, production readiness, incident response, onboarding and reorgs). Tracking ownership might just need a name, description, owner, and tier, while incident response requires more details (e.g., runbooks). Your first use case will inform what gets cataloged.

A service listing in OpsLevel includes information about its repo, owner, language, framework, system, domain, and more.

For example, in OpsLevel's own instance we want our on-call developers to find anything they might need to operate or troubleshoot a service if they’re paged, so we integrate our incident management tools with our catalog. 

Examples of what to track

What you can track in your service catalog is wide open. OpsLevel customers track hundreds to thousands of different services or components. Here are some top examples that we see often to help you get started:

  1. Core software - Microservices, monoliths, and monolith domains
  2. Libraries and packages - The stuff shared across multiple services
  3. Infra - Storage buckets, databases, infra as code configs
  4. Supporting components - Lambdas, cron jobs, ML models
  5. Tools - Internal and third party

Building out your catalog process

Now that you’ve identified your first services to catalog and defined the initial metadata necessary to get started on your primary use cases, you’re ready to start importing data. 

There are a few ways you can automate or streamline catalog creation, including our Kubernetes syncer, Terraform Provider, GraphQL API, or via Service Detection (run against your git repos). With these tools, our customers import hundreds of services in less than five minutes.

At the end of the day, some information may still live in people’s heads and need to be manually imported into OpsLevel. Service owners can do this directly in the UI or choose to manage their service definitions via YAML file.

Since there are different methods to building out your catalog, OpsLevel doesn’t lock you into any single method—mix and match as necessary. The only restriction: whenever a service is defined via YAML, it’s locked. No other method can update its core metadata.

Just getting started? You can use this spreadsheet to think through the structure you want for your catalog.

Measuring catalog impact

The catalog has intrinsic value, but it’s important to quantify how it provides value for the service owners and users (e.g., faster onboarding, better meantime to resolve issues). If you have a sense of the obstacles your teams face now, and how much they slow you down, it will help you create a before and after snapshot to gauge how OpsLevel saves time and effort (your boss will thank you). Consider these metrics to estimate impact:

  1. Adoption - How many people have used the catalog? More than once?
  2. Efficiency - How long does it take to find what you need? 
  3. Accuracy - Did searchers find what they were looking for?
  4. Effort - How hard is the catalog to maintain? How much time was spent on it?

Now that you have a stronger foundation for what constitutes a service, some ideas of what you could start to track, and a plan for building out a successful catalog, it’s time to start importing your services. We cover that in our next guide on how to build your catalog.

More resources

Guide
September 18, 2023
by
OpsLevel
Finding your IDP: A comprehensive guide to choosing an internal developer portal

This guide (and Notion template) will help you choose the right developer portal for your needs.

Guide
March 14, 2023
by
OpsLevel
How to build your catalog

Learn all the ways you can import your service metadata into OpsLevel.

Guide
March 7, 2023
by
OpsLevel
Champion's guide: How to navigate an internal developer portal rollout

Navigate your role as a champion and build partnerships across the org to ensure you can successfully implement OpsLevel and achieve your goals.

OpsLevel Logo
Subscribe
Join our newsletter to stay up to date on features and releases.
By subscribing you agree to with our Privacy Policy and provide consent to receive updates from our company.
SOC 2AICPA SOC
Product
Software catalogMaturityIntegrationsSelf-serviceBook a meeting
Company
About usCareersContact usCustomersPartnersSecurity
Resources
Docs
Blog
Demo
© 1999 J/K Labs Inc. All rights reserved.
Terms of Use
Privacy Policy
Responsible Disclosure
By using this website, you agree to the storing of cookies on your device to enhance site navigation, analyze site usage, and assist in our marketing efforts. View our Data Processing Agreement for more information.
Okay!