Using the New BlackPearl “Staging Objects” Feature

Included in Spectra Logic’s BlackPearl 5.0 API is a new Stage Objects command. Most BlackPearl customers utilize tape storage, with many using tape as the final place where data will live. Meaning, over time, the data will age out of both the cache and temporary disk tier, leaving the only copy or copies of the data on tape. Due to the secure offline nature of tape, restore jobs which mount a tape cartridge will always have some latency as it will take time to retrieve a cartridge from a shelf inside of the tape library. This latency can compound into a rather long wait if one job, with a large set of objects and partial objects, spans across many tape cartridges.

This type of latency happens frequently in many environments, since their data sets can be quite large, potentially spanning tens or hundreds of tapes. For instance, in weather forecasting, weather data is gathered over time and archived daily to new tape. When a new climate model is set to be run on the supercomputer, the job requires a sub set of data from each day in the archived time period (potentially over the last 10 years), which is stored across hundreds of tapes.

If a large restore job requires mounting many tapes, this job can take a very long time to restore the data back onto the processing server or supercomputer, especially if there is a limit on drive availability. This waiting can waste time and money because data is sitting idle on expensive compute storage waiting for the rest of the data set to arrive before performing the analysis.

With the Stage Objects command, this same job can be given to BlackPearl and it will instead internally copy the data to either a disk tier, if available, otherwise it will copy the job to cache. Later, when the window of processing time is available, a normal bulk get job can restore the data from BlackPearl disk more efficiently and quickly, since the data is pulled in parallel without additional latency required mounting tapes.

Once the data is restored to disk, the staged objects will stay on the disk as dictated by the disk policy. For example, if the data is restored to ArcticBlue disk that has a 3-month retention policy policy, the data will stay on the disk for at least 3 months. If it’s restored to disk cache, it will stay on cache for as long as the cache can keep it there until it has to make room for other files.

Creating a Stage Objects job works just like creating a bulk get job, but instead of the operation being “START_BULK_GET”, it is instead “START_BULK_STAGE”.

Here is the HTTP request syntax:

PUT http[s]://{datapathDNSname}/_rest_/bucket/{bucket UUID or name}?operation=START_BULK_STAGE[&name={string}]​[&priority=URGENT|​HIGH|​NORMAL|​LOW]

The payload will include some number of objects:

<Objects
<Object Name=”{string}” Length=”{64-bit integer}”
Offset=”{64-bit integer}” Version_Id=”{string}”/>

</Objects>

The response is same as other bulk jobs:

<MasterObjectList
Aggregating=”TRUE|FALSE”
BucketName=”{string}”
CachedSizeInBytes=”{64-bit integer}”
ChunkClientProcessingOrderGuarantee=”IN_ORDER|NONE”
CompletedSizeInBytes=”{64-bit integer}”
EntirelyInCache=”TRUE|FALSE”
JobId=”{string}”
Naked=”TRUE|FALSE”
Name=”{string}”
OriginalSizeInBytes=”{64-bit integer}”
Priority=”CRITICAL|URGENT|HIGH|NORMAL|LOW|BACKGROUND”
RequestType=”GET”
StartDate=”YYYY-MM-DDThh:mm:ss.xxxZ”
Status=”IN_PROGRESS|COMPLETED|CANCELED”
UserId=”{string}”
UserName=”{string}”>
<Nodes>
<Node EndPoint=”{string}” Id=”{string}”/>
</Nodes>
<Objects
ChunkId=”{string}”
ChunkNumber=”{32-bit integer}”>
<Object Id=”{string}” InCache=”TRUE|FALSE”
Latest=”TRUE|FALSE” Length=”{64-bit integer}”
Name=”{string} “Offset=”{64-bit integer}”
VersionId=”{string}”/>

</Objects>

</MasterObjectList>

This Staging Objects operation is available in all 5.0+ SDKs for integration into your application. We encourage developers to use this new feature to pre-stage data for users of their applications. Contact the Developer Program Team if you have any questions or need assistance.


BlackPearl SDK for Go is Now Available

Spectra Logic provides software development kits (SDKs) to make it easier to create applications that integrate with BlackPearl. We are pleased to announce that now we have an SDK for the Go programming language to simplify and accelerate BlackPearl client application development. In addition to Go, we currently support SDKs for Java, C#/.NET, C and Python. You can download the Go SDK and view the Go SDK documentation. This is a new language release, so please send us any feedback you might have on this SDK.


Getting Started with BlackPearl Partial File Restore Integration

In ​the Media & Entertainment world​, data files have reached very large sizes,​ particularly in cases of high resolution video ​that can exceed the one terabyte in size. In order to efficiently work with very large files, the media file processing is done in sections, with​ the end-user requesting content “snippets” based on timecodes. Object storage devices​​ that are used to store very large files are typically not aware of the timecode-to-byte relationship, and have no content awareness that’s necessary to extract and create partial media files.  In order to bridge the gap between time and bytes, BlackPearl has added a Partial File Restore (PFR) feature to enable the media processing application to efficiently retrieve a complete media file based on timecode offsets.

In​​ a typical Media Asset Management (MAM)/BlackPearl environment, the architecture would involve the following elements:

--        MAM – provides end user interface

--        BlackPearl MAM Plugin – handles all interactions between BlackPearl and MAM

--        BlackPearl – object storage

--        PFR Server – provides PFR processing services

--        NAS – network storage – permanent storage location for index files, temporary storage location for file processing

 

In the BlackPearl environment, there are two parts to the PFR processing of media files. The first part involves creating the media-aware index file for timecode/byte-offset information during file storage (writing) process. The second part of the process involves recalling a range of bytes that are based on a specified timecode, and creating complete, a self-contained media file that contains only the requested frames. In order to make this integration efficient, the PFR Server has a defined set of services that can be called by the media application using a REST interface (in this architecture – via the BlackPearl plugin).

The interface supports three basic request calls and two status calls to monitor the progress of the requested execution:

--        Request File Indexing
--        Request File Indexing Status
--        Request File Byte Offsets
--        Request Partial File Creation
--        Request Partial File Creation Status

For storing the file, the typical flow of execution would be:

  1. Copy media file to NAS storage
  2. Request creation of media index file
  3. Monitor status for completion
  4. Write file to BlackPearl Storage

For retrieving the partial file, the flow of execution would be:

  1. Request File Byte Offsets based on timecode
  2. Read specified byte range from BlackPearl to NAS
  3. Request partial file creation
  4. Monitor file creation status
  5. Supply partial file to Media Application

Spectra’s development team has created an C# and Java SDKs to support the rapid development and integration of the PFR with BlackPearl Storage into existing M&E environments. The SDKs provide “wrapper” calls for the REST API calls. The C# and Java client documentation and code samples can be found at:

https://github.com/SpectraLogic/tpfr_client

https://github.com/SpectraLogic/tpfr_java_client

PFR Users Guide provides the list of supported video file formats.

Quick Start Guide is a required reading to understand the services and locations that have to be setup in order to start PFR development.

PFR REST API definition is available for direct HTML development.

If you are considering creating a PFR integration with a BlackPearl environment, please contact the Spectra Logic Developer Program Team.


Minimizing Changes to the BlackPearl API

Spectra Logic’s BlackPearl is a gateway to our deep storage that uses an Application Programming Interface (API) for archive and restore operations. This API is used by our partners to integrate their software with BlackPearl. With the success of BlackPearl, the list of partner software clients is growing quickly. With the larger list comes a very important question: what should Spectra do to keep changes in BlackPearl code from affecting partner integrations? Retesting every release of BlackPearl code with every client version is obviously not feasible. Instead, Spectra Logic has chosen to tightly control and minimize API changes to prevent problems with partner integrations. To achieve this, we have established an API change review process that involves all stakeholders within the Spectra organization, as well as external partners and customers.

The release process:

-- Requires that every type of proposed change to an existing API call has a sponsor and is logged in the engineering feature tracking system.

-- The proposed change has to be reviewed and approved by both Spectra’s Engineering and Product Management departments before it becomes scheduled for development.

-- Even when approved, any changes to API with potential to affect partners and customers have to be scheduled with sufficient lead time to allow proper communications to and changes by all stakeholders, including customers, partners, and Spectra Logic.

-- Finally, the process restricts API changes which affect backward compatibility with existing clients to major releases of BlackPearl code (e.g. version 3.x to version 4.x), unless the change is deemed critical by the directors of both Engineering and Product Management departments.

-- New XML response elements and attributes are permitted, as they should be ignored by clients not taking advantage of a new response element. This behavior allows existing older clients to keep functioning with newer versions of API.

 

With all the controls built into the process, Spectra Logic aims to assure a stable and consistent API for interfacing with BlackPearl. At the same time, the process provides a means to expand the API to meet the needs of end users and support new applications and markets as they develop in the future.