Service cataloging 101: What should you track?

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.

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’ll cover that in Service cataloging 102.