Extending Pipeline Feedback Scope with Enhanced API

Post

This is the third blog in a series of blogs on Pipeline Feedback. In the first blog, Increasing Agility with Pipeline Feedback Scoping, we discussed the different types of pipeline feedback scope. In the follow up post, Applying Pipeline Feedback Scope to Uncover Hidden Dependencies, we looked at how to best apply pipeline feedback scope. To keep things simple and consistent, the same monitoring example from the first two blogs is used for illustration.

Pipeline Feedback API Overview

The Pipeline Feedback Releases  API has been updated to accommodate the new capabilities discussed in the previous two blog posts. In doing so, there were several factors that were considered:

  • Backwards compatibility so that existing users would not be impacted and their current business processes can continue. This meant extending the Application API rather than replacing or versioning it.
  • It is shell scripting and curl friendly since many build systems make Application API calls using CURL and users often learn by experimenting with CURL.
  • User friendly using Service Name and Application Names rather than internal IDs.
  • Allow users to mix different scopes with the same release marker so that only a single API call is needed.

Other standard REST practices were followed as well.

The enhanced API can assign a marker for the following cases using a single API call:

  • A global marker;
  • A single service;
  • Multiple services;
  • A single Application Perspective;
  • Multiple Application Perspectives;
  • A service marker in an Application Perspective; and
  • Multiple service markers in an Application Perspective.

The API allows for these cases to be mixed except for the global marker which subsumes all the other cases. Let’s look at some examples by examining the payload and ignoring the other details.

Create a Global Marker at the Current Time

The simplest API call that can be made is for a global marker. The payload is shown below. The current version of the API requires including the epoch timestamp so it is added. A future enhancement is to make this optional and use the time the API was called. A 200 status is returned since this creates a marker.

{
     "name": "Global Scope", // Current implementation
      "start": 1602852068000
}

The response payload echoes the name and start time of the global marker. The marker ID is returned and this is used for other actions, such as deleting the newly created marker. An additional result is the time the marker was last updated which is the same as the creation time. This response payload is common with only a couple of variations.

{
     "id": "123456",
     "name": "Global Scope",
     "start": 1602852068000,
     "lastUpdated": 1602852068000
}

Please note that the timestamp is in milliseconds since the Epoch. Instana presents time in milliseconds and this convention is used in the Application APIs, unless otherwise noted. So the timestamps have three digits more than the usual values you get with, say, a date +%s. This is shown in the prior examples.

Create Multiple Services at Once

The API payload below creates a service marker for three services: Serv1, Serv2, and Serv3. It specifies the start time to apply the marker at which is epoch time in milliseconds.

{
     "name": "Service Scope",
     "start": 1602852068000,
     "services": [ // three services all have the same marker name and ID
          {
               "name": "Serv1"
          },
          {
              "name": "Serv2"
          },
          {
              "name": "Serv3"
          }
     ]
}

The 200 Response is returned since all items were processed successfully with the payload:

{
     "id": "123456",
     "name": "Service Scope",
     "start": 1602852068000,
     "lastUpdated": 1602852068000
}

The API is considered transactional because either: all of the requests succeed with a 20x return code or (2) none of them do and a 400 is returned. For example, if the service “Serv2” could not be found then neither Serv1 or Serv3 are updated and a status of 404 is returned. As shown below the body of the returned response would identify that the service was not found.

{
     "notFound": {
                     "services": [ {"name": "Serv2", “reason”:”Not found” } ]
     }
}

Create Multiple Applications at Once

Similarly multiple applications can have the same release marker assigned. This is shown below where the Application Perspectives App1, App2, and App3 have the release marker “Application Scope” assigned.

{
     "name": "Application Scope",
     "start": 1602852068000,
     "applications": [ // three applications with the same marker name and ID
          {
              "name": "App1"
          },
          {
              "name": "App2"
          },
          {
              "name": "App3"
          }
     ]
}

If all of the Application Perspectives have the release marker assigned then a 200status is returned:

{
     "id": "123456",
     "name": "Application Scope",
     "start": 1602852068000,
     "lastUpdated": 1602852068000
}

If there was a problem assigning any of the markers then none of the markers are assigned and a 400 status is returned. The body of the response would help to identify the error.

Create a Service Scoped to Two Applications

The code sample below creates a service marker for Service1 in the two application perspectives: App4 and App5. In this case the scopedTo attribute defines the applications to scope the marker to. The response behavior is the same as above (i.e., Service1, App4, and App5 need to exist).

{
     "name": "Service scoped to an application",
     "start": 1602852068000,
     "services": [
          {
             "name": "Service1", // Service1 is service scoped within
             "scopedTo": {
                 "applications": [
                     {
                         "name": "App4"
                    },
                    {
                         "name": "App5"
                    }
                ]
            }
         }
    ]
}

Create One of Everything, Except Global Marker

The next example creates one of everything with an assigned marker of “Multi scoped request”.

{
     "name": "Multi scoped request",
     "start": 1602852068000,
     "services": [
         {
             "name": "Serv1"
         },
         {
             "name": "Serv2"
         },
         {
             "name": "Serv3"
         },
         {
             "name": "Service1", // Service1 is service scoped within
             "scopedTo": {
                 "applications": [
                     {
                         "name": "App4"
                     },
                     {
                         "name": "App5"
                     }
                 ]
             }
         }
     ],
     "applications": [
         {
             "name": "App1"
         },
         {
             "name": "App2"
         },
         {
             "name": "App3"
         }
     ]
}

Replace One of Everything

It is possible to update a release marker by reading its existing state, modifying that state, and then PUTing the updated state back into the release marker. The release marker is identified by its ID. The example below does this. Again, either the entire operation succeeds or nothing is updated.

The API semantics for a PUT support deleting a service or application, as well as adding a service or application. For example, if service is not found then the item is deleted from the marker. Similarly if a new service is found then add that service to the marker. The application semantics are the same.

{
     "name": "Replace with one of everything",
     "start": 1602852068001,
     "services": [ // Serv1 is deleted because it is no longer here
         {
             "name": "Serv2" // Serv2 is kept since it appears again
         },
         {
             "name": "Serv3" // Serv3 is kept
         },
         {
             "name": "Serv4" // Serv4 is added
         },
         {
             "name": "Service2", // Service2 scoped to App5 and App6 is added
             "scopedTo": {
                 "applications": [
                     {
                         "name": "App5"
                     },
                     {
                         "name": "App6"
                     }
                 ]
             }
         }
     ],
     "applications": [ // App1 is deleted because it no longer is here
         {
             "name": "App2" // App2 stays
         },
         { // App3 is deleted since it no longer is here
             "name": "App4" // App4 is added
         }
    ]
}

If a service or application does not exist then a 400 status code is returned and the response body indicates the source of the error. An example is shown below:

     {
     "id": "123456",
     "name": "Replace with one of everything",
     "start": 1602852068001,
     "lastUpdated": 1602852068000 // Time of update
      "notFound": {
         "applications": {
             [
                 "name": "App7", “reason”:”Some text”
             ]
         },
         "services": {
             [
                 "name": "serv1", “reason”:”Some text”
             ]
         }
     }
}

Tool Integration

Pipeline Feedback integrates with several tools and platforms through which Instana ingests data about releases so users see a release as a chart annotation. The supported tools are:

The Release Application API can be used to enable integration with other tools as well.

Navigating to a Build

The ability to navigate to a build has been enhanced to show the scope of the release. This is shown in the Time Control dropdown below, where the user selected the Releases tab. The scope is shown in the orange rectangle where it has marker examples that include a global, application, or service marker.


Word Image 364

Summary

Pipeline Feedback can assign a release marker in several different scopes:

  1. Using the Application Perspective name that scopes an application marker based on the Application Perspective’s context in the services or endpoints in the Application Perspective;
  2. A service name where the service marker is shown in all Application Perspective dashboards with that service and the service dashboard for that service ;
  3. A service name in an Application Perspective where only that Application Perspective shows that service marker; and
  4. A global marker that is shown everywhere.

This is a toolbox that can be combined in several ways such as: the same marker can be set on multiple Application Perspectives; or the same marker can be set on multiple services; or both. There have been several examples of how to apply these tools as well. Now the teams in an enterprise to assign the release markers that are specific to their team, as well as a foundation for the next set of Pipeline Feedback capabilities.

Play with Instana’s APM Observability Sandbox

Featured
CircleCI is a CI/CD platform that lets teams build and deliver software quickly and at scale. They make delivering great software simple in both the cloud and on your own infrastructure. New...
|
Announcement, Conceptual, Developer, Engineering, Product
According to AWS: “[Graviton2 is] custom built by Amazon Web Services using 64-bit Arm Neoverse cores to deliver the best price performance for your cloud workloads running in Amazon EC2” At Instana...
|
Announcement, Developer, Product
Understanding the health status of your systems is important, and Observability tools, such as Instana, help you to achieve deep insights into every element of the overall architecture. As long as everything...
|

Start your FREE TRIAL today!

Instana, an IBM company, provides an Enterprise Observability Platform with automated application monitoring capabilities to businesses operating complex, modern, cloud-native applications no matter where they reside – on-premises or in public and private clouds, including mobile devices or IBM Z.

Control hybrid modern applications with Instana’s AI-powered discovery of deep contextual dependencies inside hybrid applications. Instana also gives visibility into development pipelines to help enable closed-loop DevOps automation.

This provides actionable feedback needed for clients as they to optimize application performance, enable innovation and mitigate risk, helping Dev+Ops add value and efficiency to software delivery pipelines while meeting their service and business level objectives.

For further information, please visit instana.com.