Synapse Status and Maintenance Modes

A synapse stack can be in the following modes:

Mode	Accepted (200)	Unavailable (503)	Description
READ_WRITE	GET, PUT, POST, & DELETE	none	This is the standard operating mode for Synapse. While in this mode all HTTP methods will be accepted (200s).
READ_ONLY	GET	PUT, POST, & DELETE	While in this mode Synapse is read-only. While in this mode PUT, POST, and DELETE will all result in a 503 (Service Unavailable) response.
DOWN	none	GET, PUT, POST, & DELETE	While in this mode Synapse will return 503 (Service Unavailable) for any non-administration call

Note: Any 'reop/v1/admin/' will be accepted (200s) for any mode including READ_ONLY and DOWN. *

Getting the Current Stack Status

The following example shows how to get the current status. Note: This call does not require an authentication token.
Request

curl -i -k -H Accept:application/json -H Content-Type:application/json http://localhost:8080/services-repository-0.8-SNAPSHOT/repo/v1/admin/synapse/status

Response

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 10 Dec 2011 23:35:07 GMT
{
    "status":"READ_WRITE",
    "pendingMaintenanceMessage":"Synapse will be down for maintenance Saturday 12/10 from 11:58 to ll:59.",
    "currentMessage":"Synapse is currently up and running."
}

There are two messages associated with the current status.

currentMessage - This is the massage that is returned with any 503 (Service Unavailable) response. It is used to inform the caller of the current state. The administrator should set the message whenever the status changes.
pendingMaintenanceMessage - This message shows pending maintenance information. This can be shown to end users to let them know of upcoming down time.

Updating the Current Status

Only an administrator can change the current status of Synapse. The administrator can set all three fields (status, currentMessage, and pendingMaintenanceMessage) with a single call:
Request

curl -i -k -H sessionToken:<your admin token> -H Accept:application/json -H Content-Type:application/json -X PUT -d '{
  "status": "DOWN",
  "currentMessage": "Synapse is currently DOWN for maintenance.  It will be back up in few minute.",
  "pendingMaintenanceMessage":null,
}' http://localhost:8080/services-repository-0.8-SNAPSHOT/repo/v1/admin/synapse/status

Response

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 10 Dec 2011 23:47:18 GMT
{
    "status":"DOWN",
    "currentMessage":"Synapse is currently DOWN for maintenance.  It will be back up in few minute."
}

StackStatus JSON Schema

{
    "description":"The Status of the stack",
    "properties":{
        "status":{
            "type":"string",
            "description":"The status of this stack can be one of the following enumerations",
            "name":"StatusEnum",
            "id":"org.sagebionetworks.repo.model.status.StatusEnum",
            "enum":[
                "READ_WRITE",
                "READ_ONLY",
                "DOWN",
             
            ],
            
        },
        "currentMessage":{
            "type":"string",
            "description":"This message applies to the current state of the stack."
        },
        "pendingMaintenanceMessage":{
            "type":"string",
            "description":"This message is used to notify users of pending maintenance"
        },
        
    }
}

Storage Usage

Check the (external) storage usage by the Synapse system. You must be an administrator to perform these actions.

Get aggregated totals

Aggregated over any combination of dimensions listed in StorageUsageDimension (see StorageUsageDimension in Synapse Entity Types) except for USER_ID and ENTITY_ID which are provided via separate APIs. For example, the following command lists storage usage by content type and storage provider:

curl -i -H sessionToken:<token> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/admin/storageSummary?aggregation=CONTENT_TYPE,STORAGE_PROVIDER

Will get results like the following

{
    "summaryList": [
        {
            "aggregatedCount": 181, 
            "aggregatedSize": 5409454583, 
            "dimensionList": [
                {
                    "dimension": "CONTENT_TYPE", 
                    "value": "application/binary"
                }, 
                {
                    "dimension": "STORAGE_PROVIDER", 
                    "value": "awss3"
                }
            ]
        }, 
        {
            "aggregatedCount": 9, 
            "aggregatedSize": 0, 
            "dimensionList": [
                {
                    "dimension": "CONTENT_TYPE", 
                    "value": "application/binary"
                }, 
                {
                    "dimension": "STORAGE_PROVIDER", 
                    "value": "external"
                }
            ]
        }, 
        {
            "aggregatedCount": 3, 
            "aggregatedSize": 195333619, 
            "dimensionList": [
                {
                    "dimension": "CONTENT_TYPE", 
                    "value": "application/octet-stream"
                }, 
                {
                    "dimension": "STORAGE_PROVIDER", 
                    "value": "awss3"
                }
            ]
        }, 
        {
            "aggregatedCount": 3590, 
            "aggregatedSize": 0, 
            "dimensionList": [
                {
                    "dimension": "CONTENT_TYPE", 
                    "value": "application/octet-stream"
                }, 
                {
                    "dimension": "STORAGE_PROVIDER", 
                    "value": "external"
                }
            ]
        }, 
        {
            "aggregatedCount": 19, 
            "aggregatedSize": 9927282, 
            "dimensionList": [
                {
                    "dimension": "CONTENT_TYPE", 
                    "value": "application/pdf"
                }, 
                {
                    "dimension": "STORAGE_PROVIDER", 
                    "value": "awss3"
                }
            ]
        }, 
        {
            "aggregatedCount": 8370, 
            "aggregatedSize": 0, 
            "dimensionList": [
                {
                    "dimension": "CONTENT_TYPE", 
                    "value": "application/x-tar"
                }, 
                {
                    "dimension": "STORAGE_PROVIDER", 
                    "value": "external"
                }
            ]
        },
    ] 
}

Without any aggregation, the same URL will get only the grand totals.

curl -i -H sessionToken:<token> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/admin/storageSummary

{
    "totalCount":133827,
    "totalSize":1080865415607,
    "summaryList":[]
}

Get usage by users

Lists the aggregated usage by users in descending order of 'aggregatedSize':

curl -i -H sessionToken:<token> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/admin/storageSummary/perUser

Example response body listing the top 3 users:

{
    "summaryList": [
        {
            "aggregatedCount": 35204, 
            "aggregatedSize": 283329626902, 
            "dimensionList": [
                {
                    "dimension": "USER_ID", 
                    "value": "273975"
                }
            ]
        }, 
        {
            "aggregatedCount": 458, 
            "aggregatedSize": 227459357704, 
            "dimensionList": [
                {
                    "dimension": "USER_ID", 
                    "value": "342024"
                }
            ]
        }, 
        {
            "aggregatedCount": 179, 
            "aggregatedSize": 66928683678, 
            "dimensionList": [
                {
                    "dimension": "USER_ID", 
                    "value": "274010"
                }
            ]
        },
        ...
    ]
}

Get usage by entities

Lists the aggregated usage by entities in descending order of 'aggregatedSize':

curl -i -H sessionToken:<token> -H Accept:application/json https://repo-staging.sagebase.org/repo/v1/admin/storageSummary/perEntity

Example response body listing the top 3 entities:

{
    "summaryList": [
        {
            "aggregatedCount": 1, 
            "aggregatedSize": 5210220350, 
            "dimensionList": [
                {
                    "dimension": "NODE_ID", 
                    "value": "317475"
                }
            ]
        }, 
        {
            "aggregatedCount": 1, 
            "aggregatedSize": 4670860925, 
            "dimensionList": [
                {
                    "dimension": "NODE_ID", 
                    "value": "1113803"
                }
            ]
        }, 
        {
            "aggregatedCount": 2, 
            "aggregatedSize": 4235837739, 
            "dimensionList": [
                {
                    "dimension": "NODE_ID", 
                    "value": "4494"
                }
            ]
        }, 
        ...
    ]
}